Apps and Versions

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

📦 Applications

Applications encapsulate 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 or requirements.

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, 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 dashboard, or our API.

Explore our App versions API reference, or read more about 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.

🧱 Required Parameters

These fundamental parameters must be always defined.

Resource Requirements

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.

Image Details

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 or use latest tag to avoid deploying outdated (cached) builds. ✅ DO - increase your version tag always to deploy the intended build and prevent release issues.

• 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.

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.

⚙️ Optional Parameters

These parameters may be configured to further customize your deployments.

Injected Variables

Custom environment variables will be injected for all deployments on this version:

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

• see Injected Variables for understanding different ways environment variables can be injected depending on deployment’s context, in addition to app version variables,

• each environment variable may contain up to 4KB (kilobytes) of string data.

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

Active Caching

🌟 Upgrade to Pay as You Go tier to unlock 0.5 second deployment time worldwide!

Speed up deployments and start servers within seconds, no standby servers required. Server image associated with this app version will be preloaded in all of our worldwide locations automatically.

Caching will take full effect once your app version's caching level reaches 🟢 Good.

Multiple app versions may reuse the same image tag. Enabling cache for one version will enable it for all versions linked with the same image tag automatically, making parametrized deployments easy.

Image is also passively cached at deployment, only on the host machine where it was deployed.

Images are removed from cache if they aren't deployed for 72 consecutive hours.

Port Mapping

Each server requires at least one port in order to accept incoming client connections:

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

• Protocol will depend on your netcode integration transport,

• 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.

Most games will only require adding a single UDP port mapping for port 7777.

While internal ports for the server process are defined as part of app version, external ports are assigned at random once a deployment is created, so that a potential malicious party (hacker) is slowed down and detected before they can cause damage.

Add more ports in your port mapping if your server communicates over multiple protocols.

Safety Guardrails

These parameters help with various edge cases and general server troubleshooting:

• 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, or set to -1 with app version API create/edit for Persistence with Private Fleets.

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

• Container Log Storage - to export server logs after deployment stops, specify pre-configured S3-compatible bucket to export your container logs,

  • 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.

⏩ Update 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.