Apps and Versions

Learn about versioning and applications - concepts and best practices for deeper understanding.

📦 Applications

Applications encapsulate your individual server projects. This separation of context is particularly useful if you:

• work on multiple games or non-game projects (consolidated billing),

• work on external projects as a co-developer (transfer ownership later),

• depend on multiple loosely coupled server types with different scaling patterns.

You can manage your Applications on Edgegap using our plugins, dashboard, or our API.

Explore our Applications API reference, or read more about our Management API.

🏷️ App Versions

As you develop your application and continuously produce new builds, you will need to store each build as a separate version to:

• maintain compatibility between your clients and server,

• compare various aspects of your incremental releases (performance, quality, user sentiment),

• test multiple app versions simultaneously (development, quality assurance, staging, beta).

Each App version points to one build artifact of your choice. Multiple versions may point to the same build.

You can manage your App versions on Edgegap using our plugins, dashboard, or our API.

Explore our App versions API reference, or read more about Management API.

Each version is uniquely identified within it’s parent Application by App version name. You are free to decide your own naming convention. Here’s a few popular examples to inspire your choice:

• 2024.01.30-16.23.00-UTC - timestamps are transparent for keeping many past versions,

• 1.1.0 - semantic versioning is a great choice to communicate scope of changes,

• dev , staging, qa, prod - keeping only the latest version per environment is very easy,

• blue, green - versions can be used as aliases for a rolling update release strategy.

You can change your approach at any time, as long as you maintain client/server compatibility.

You may disable any App or Version in our dashboard to safeguard against human (dev) errors.

Free Tier is limited to 2 Applications, 2 versions, and 5 GB of Container Registry storage.

Combine Versioning Strategies

Oftentimes, the best solution is a mix of versioning strategies, for example:

• using timestamps or semantic versioning for dev builds, for more granular tracking;

• keeping staging, qa and prod versions with environment-specific parameters;

• alternating blue and green versions as aliases for zero matchmaking downtime updates.

Resource parameters (required)

In addition to the version’s name, several parameters are required to create a new version:

• vCPU - how many virtual CPU units your app needs to run (1024 units = 1 vCPU),

  • the minimum allowed vCPU amount is 0.25 vCPU (256 units),

  • this setting can’t be edited on an existing App version, you must create a new version.

• Memory - how many megabytes of RAM your app needs to run (1024MB = 1GB),

  • this setting can’t be edited on an existing App version, you must create a new version.

• GPU - how many Graphical Processing Units your app needs to run,

  • this feature is not available yet, please contact us if you’re interested.

Versions automatically include RAM in 2:1 RAM-vCPU ratio, allowing up to 512MB of RAM per 0.25 vCPU.

Our server machines use AMD/Intel CPUs with clock speed 2.4 - 3.2 GHz, varying by location. To ensure your server has sufficient resources available, reach out on Community Discord.

Container parameters (required)

These parameters will help our system decide which build of your server should be started later:

• Registry - registry.edgegap.com if you’re using our Container Registry,

  • to use a third party registry input your third party registry docker credentials,

  • registry serves as a shared storage service for your and other user’s repositories.

• Image Repository - refers to your Application’s dedicated repository,

  • find all of your repositories on our dashboard’s Container Registry page,

  • each repository may include multiple tags of your server image.

• Tag - refers to a specific build artifact (version) of your server image,

  • our plugins copy the tag values from App version names by default,

  • you can view locally stored tags in Docker Desktop Images or using docker CLI.

DO NOT overwrite existing tags to ensure that you always deploy the intended server build. Overwriting Tags may cause the app version to deploy your old (outdated) build using the cached docker image.

• Private Registry - if your repository’s access is protected (private repository), we’ll also need:

  • Username Token - your registry’s programmatic access username,

  • Password Token - your registry’s programmatic access password,

  • for Edgegap Container Registry, you may copy these values from our dashboard,

  • these are not required for public repositories.

Power users - see ✏️ Customize Server Image.

Troubleshooting and FAQ

I received error 401 Unauthorized when pushing my server image.

• This means you haven’t signed in to your container registry. See Container Registry for Edgegap Container Registry instructions, or the equivalent for your registry provider. Repeating your last operation will not resolve the error.

---

I received error 403 Forbidden when pushing my server image.

• This means that either your currently signed in registry user doesn’t have sufficient permissions (typically to push a new image), or that you are signed into the incorrect registry provider. Try signing out and signing in with the correct provider and user with sufficient permissions. Repeating your last operation will not resolve the error.

---

What is the difference between a registry, repository, and a project?

• Think of registry as a storage facility, repository as a storage unit, and project as a storage unit number. Each registry typically includes many repositories, some public, some private to organizations and users.

• Example registry: registry.edgegap.com .

• Example repository: registry.edgegap.com/my-edgegap-org/my-game-server.

• Example project name: my-game-server .

---

When pushing new image tags / builds my changes are not reloading correctly.

• Make sure that every time you rebuild, you push with a new image tag. Edgegap’s internal caching system uses tag names and in case you overwrite a tag value (e.g. latest) it will not pick up on the new build.

---

Can I tag the same build artifact multiple times?

• Yes, you can tag the same artifact multiple times without issues, serving as multiple aliases to the same build. Keep reading to learn how to remove the tags later.

---

What happens when I delete a tag? Why can’t I delete a specific artifact using a hash?

• Deleting a tag will also cause the associated build artifact to be deleted, if there are no other tags associated with the artifact at the time of the API request.

• Due to docker API standards and to ensure best possible user experience, we only provide an interface for deleting tags. See point above regarding deleting build artifacts.

Other parameters (optional)

You may additionally specify optional parameters such as:

• Session Type - this setting enables custom integration of lobbies and drop-in/drop-out:

  • learn more about Matchmaking.

• Time Constraints - these features can help you manage deployments’ resource lifecycle,

  • Game Max Duration can be set to gracefully shut down your servers after a given period,

  • Maximum time to deploy can help you clean up deployments taking too long to start.

• Activate Caching - in order to speed up deployment time, members may enable app version caching with a single click in all of our worldwide locations:

Caching reduces deployment time to a few seconds and improves players experience substantially.

• Ports - each server will require at least one port in order to accept client connections:

  • Port value refers to the internal port value, usually from your netcode integration,

  • Protocol will depend on your netcode integration specifics,

  • Name is a human-readable identifier for your own needs, may be the same as Port,

  • Verifications can be enabled to ensure your container is initialized before marked READY.

To learn more about protocols, ports, and more, see Discoverability. Add more ports in your port mapping if your server communicates over multiple protocols.

• Environment variables - these custom values will be injected for all deployments on this version:

  • common examples include: engine arguments, third party secrets and endpoints,

  • see also Injected Environment Variables for understanding different ways environment variables can be injected depending on deployment’s context,
  • each environment variable may contain up to 4KB (kilobytes) of string data.

Make sure to set your sensitive environment variables (secrets, tokens) as hidden for added security!

• Container Log Storage - you may specify your own pre-configured S3 bucket for our system to export your container logs to at the deployment termination stage,

  • see Endpoint Storage for details on configuration and usage.

Logs of versions without external Storage will be deleted on deployment termination.

Free Tier is limited to 2 Applications, 2 versions, and 5 GB of Container Registry storage.

Troubleshooting and FAQ

How can I change an app version’s CPU and memory settings?

• Open your app version in our dashboard, and click on Duplicate. This will pre-fill all parameters from the original version, letting you edit any, including resources.

---

When should I use Seat or Match Session type?

• Only use Seat or Match Sessions if you’re aiming to implement a custom matchmaking integration. Our Gen2 matchmaker uses Default deployments for all features.

• Seat Session type is suitable for games with solo players dropping in or out of servers at any time, such as MMOs, sandbox games, or asynchronous multiplayer games.

• Match Session type is suitable for games with variable group size, with solo players acting as a group of one player, typically used for servers capable of running multiple matches concurrently.

---

What will happen if a player leaves my deployment?

• By default, servers don’t reject player connections. Authenticating players is up to your devs, since many different methods and player authentication providers can be used.

• Game clients may store connection information locally to attempt reconnecting in case of unexpected client crashes.

• To allow players to join games in progress, consider using Backfill or Sessions.

---

My caching never completes fully, stuck at X %.

• Since our platform dynamically adds and removes new server machines depending on studio needs, caching is likely to never reach 100%, even though new machines will start caching your server image as soon as possible.

• Reaching 70% caching level is typically sufficient for a smooth rollout.

---

What if I deploy on a server machine without my cached image?

• The first startup without cache may take longer, up to 1-2 minutes, since the machine has to download the image. Every subsequent deployment on the same machine will reuse the image which has been cached during the first deployment.

---

Why do I need to use containers with Edgegap?

• Using containers ensures that your server dependencies are always consistent, removes the need to individually maintain server machines, and ensures that other deployments on the same machine will not impact the deployment.

• We recommend watching "Never install locally" (video).

Configuration Consistency

In order to ensure that none of the parameters change when you create a new App version through our dashboard, we recommend using the Duplicate feature in the top right corner of your previous App version’s dashboard page. When duplicating, you may edit any parameters before saving.

Duplicating or editing your App versions does not require rebuilding your server image.

See Matchmaker Rolling Updates for further automation of releases.