Getting Started - Servers

Learn by doing and deploy your first Dedicated Server on Edgegap.

✔️ Preparation

⚡ Deploy Your First Dedicated Server on Edgegap

By the end of this guide, you will have deployed a dedicated server with Edgegap at no cost.

1. Connect your Edgegap Account

☑️ To get started, we’ll need you to create a free account with Edgegap. No credit card required.

☑️ Once you’re signed in, please verify there are no new errors in your Unity console.

✅ You may now proceed to the next step.

2. Build your Game Server

Whether you’re using a Windows, Mac, or a Linux machine, you will need to build your server for Linux runtime, as most cloud providers nowadays (including Edgegap) run on Linux. Don’t worry, no Linux knowledge is required to accomplish this with our plugin.

☑️ Validate you have installed the required Unity Linux build tools.

Install Unity Linux Build Support modules

• Use Unity Hub to select tab Installs, access Settings and Add Modules for each Unity version you intend to use with Edgegap platform:

• Scroll down to select and install the following Unity modules:

  • Linux Build Support (IL2CPP),

    • Linux Build Support (Mono),

    • Linux Dedicated Server Build Support

☑️ Once you’re happy with your configuration hit Build server, wait for the process to finish and verify there are no new errors in your Unity console. Completing this step will result in a new folder appearing in your project root - Builds/EdgegapServer/ServerBuild .

✅ You may now proceed to the next step.

3. Containerize your Game Server

Working in a team of developers means sharing your code. When things go wrong, the last thing you want to hear is “it works on my machine”. Game servers have to run reliably on any machine, since a successful games’ servers will run on thousands of server machines across the world.

To help make your server reliable, we use Docker - virtualization software to ensuring that all of your server code dependencies down to the operating system level are going to be always exactly the same, no matter how or where the server is launched.

☑️ For now, start by hitting the Validate button to ensure you’ve completed Usage Requirements.

• Install Docker Desktop from the official source

☑️ You may configure the following options (or keep defaults):

• Build path is the relative path to your server build artifact, let’s keep the default for now.

• Image name is a unique identifier of your choice, labeling your server build before shipping.

  • Usually, this will include the name of your game - for example “my-game-server”.

• Image tag is an identifier pointing to a specific version of your image.

  • The term “build artifact” is sometimes used to refer to a specific version of your image.

  • Timestamps are a great option for tagging, e.g. 2024.01.30-16.23.00-UTC .

• Path to Dockerfile can be used to customize the recipe for your images.

  • We recommend keeping the default setting for now, you can read more later in section ✏️ Customize Server Image.

• Optional docker build parameters can be used to further instruct Docker on finer nuances.

  • We recommend keeping the default setting for now, you can read more later in Docker docs.

☑️ Once you’re happy with your configuration hit Containerize with Docker, wait for the process to finish and verify there are no new errors in your Unity console. Completing this step will result in a new image appearing in your local machine. You can verify this either in Docker Desktop, in tab Images underneath Local (default), or in docker CLI by running docker images .

✅ You may now proceed to the next step.

4. Test your Server Locally

Let’s try deploying locally (on your machine) and connecting a game client, to make sure the server image is functioning properly before we upload and deploy (which may take a bit of time).

☑️ You may configure the following options (or keep defaults):

• Server image tag from the previous step.

  • Defaults to the last tag you’ve built with the plugin.

• Optional docker run parameters can be supplied for exposing multiple ports, or running your image on macOS machines.

  • You may publish multiple ports for your container if needed, simply add the parameter -p {internal port}/{protocol} for each, for example -p 8080/tcp -p 7770/udp to publish and map your server port 8080 to a random external port for TCP connection and server port 7777 to a random external port for UDP connection at the same time.

  • Find server port configuration in your Transport or netcode-specific settings.

  • If you’re using a machine with ARM architecture (macOS M1, M2, M3, etc..) you should see this optional parameter included in your Optional docker build parameters: --platform=linux/amd64 .

☑️ Once you’re happy with your configuration hit Deploy local container, wait for the process to finish, and verify there are no new errors in your Unity console. Completing this step will result in a new container being started on your development machine.

☑️ Now it’s time to connect your Unity Editor game client to your local docker container to verify your server image is functioning properly. Find your netcode client settings and input:

• localhost or 127.0.0.1 (equivalent in most cases) in place of server IP,

• randomized external port value found in Docker Desktop / Containers / edgegap-server-test.

☑️ Once you’ve verified you’re able to connect to your local server container and play without issues, you may delete the container 🗑️ to free up resources on your machine for other programs.

✅ You may now proceed to the next step.

5. Upload to Edgegap

It’s time to ship your server! Now that your image can successfully host players, we can upload it to Edgegap and start running it anywhere in the world. In this guide, we’ll be using Edgegap’s Container Registry (storage for images).

☑️ You may configure the following options (or keep defaults):

• Application name on Edgegap can match your image name or be customized.

  • We’ve chosen to copy your image name for now.

• Application version on Edgegap can match your tag or be customized.

  • Timestamps are a great option for app version names, e.g. 2024.01.30-16.50.20-UTC .

  • Multiple application versions may point to the same image tag, such as v1.1.0 and dev .

  • Learn more about Apps and Versions later.

• Server image name from step 3. Containerize your Game Server.

• Server image tag from step 3. Containerize your Game Server.

☑️ Once you’re happy with your configuration hit Upload image and create App version, wait for the process to finish, and verify there are no new errors in your Unity console.

☑️ You will be brought to our Dashboard, where you may configure optional settings. Completing this step will result in a new Application version being created, and your build artifact being tagged and uploaded to Edgegap’s Container Registry.

☑️ You will now be prompted to define a Port for your new Application version. Make sure to set the same server port value as in step 4. Test your Server Locally from your Transport or netcode-specific settings.

✅ You may now proceed to the next step.

6. Deploy a Server on Edgegap

This is the final step in this guide, after which you will have a server deployed on Edgegap cloud, to which players from anywhere in the world can connect.

☑️ You may select the following (or keep defaults):

• Application name on Edgegap from the previous step.

  • Defaults to the last application you’ve created on Edgegap.

• Application version on Edgegap from the previous step.

  • Defaults to the last app version you’ve created on Edgegap for this Application.

☑️ Once you’re ready, hit Deploy to cloud, wait to reach Deployments, and verify there are no new errors in your Unity console. Ensure also that your Container Logs don’t show any errors and your Container Metrics don’t indicate 100% resource utilization (vCPU or memory), otherwise new player connections may be rejected, or your server stuck in a restart loop. See troubleshooting steps below to address any issues.

☑️ Completing this step will result in a new Deployment being started on your Edgegap account. Find your new deployment’s details in our dashboard.

☑️ Now we’ll perform the final test and connect your Unity Editor game client to your cloud deployment. Input the Deployment’s Host in place of server IP and the Deployment’s external port for the port value used by the game client.

☑️ Once you verify you’re able to connect to your Deployment without issues and are done testing, Stop your Deployment to free up capacity in your account for the next build. In case you encounter issues, inspect Dashboard logs of your deployment. If you can’t figure out the issue, we’re hanging out in our Community Discord and happy to help.

🙌 Congratulations on your first Deployment on Edgegap! If you’d like to learn more, keep reading.

7. Matchmaking and Next Steps

We hope you had a good first experience with your deployment on Edgegap. We’ve simplified our configuration to show you using Edgegap is easy. We hope that you will find our platform very flexible in meeting your custom designs going forward.

☑️ Learn how to stop deployments once the match concludes, and 🔄 Deployment Lifecycle.

☑️ Check if the current instance is a game client or server by reading if any of your Injected Environment Variables (e.g. ARBITRIUM_REQUEST_ID ) are set:

if (
  string.IsNullOrEmpty(Environment.GetEnvironmentVariable("ARBITRIUM_REQUEST_ID"))
)
{
  // client code
} else {
  // server code
}

☑️ Looking for inspiration? Take a peek at our Game Samples, sharing is caring!

🔧 Optimize Server Build Size

Only include what you absolutely need for your server to run.

• Copying unused files in your images results in image bloat, longer uploads, slower caching speeds, and slower overall server startup. Review Docker image optimization suggestions.

Implement conditional lazy-loading of resources.

• Exclude client-only assets by setting textures and meshes to CPU read/write disabled.

• Consider using Unity Addressables for your client builds to speed up builds and deployments by loading assets just in time, or skipping loading some assets in server builds by checking for presence of Injected Environment Variables.

Consider using multi-stage Docker builds (link).

• Separate large server dependencies to a separate image to reuse in multi-stage builds. Docker will cache each layer and simply reuse the previous version and skip uploading this part unless specifically instructed to do so, saving you bandwidth and time waiting for the upload to finish.

• If you’re not sure why one of your Dockerfile commands throws an error, try debugging locally. Create a new stage just before the issue happens (add a second FROM command), use --target to instruct the build process to stop at the problematic stage, and then docker exec -it {container} /bin/bash to enter interactive terminal inside your container. Afterwards, you can use shell commands in your base image to investigate further (e.g. top on ubuntu).

✏️ Customize Server Image

We also support adding your own Dockerfile for users who need more control over their images due to build size optimization, extraneous dependencies, or requiring more complex startup process. You may optionally supply a path to your custom Dockerfile in step 3. Containerize your Game Server. We’ll now share a few “do it yourself” tips and best practices.

Rebuild only assets that changed since last build.

• Consider using Unity’s Incremental Builds to speed up your build time.

Having issues when using Websockets, or HTTPS requests?

• If you’re getting Curl error 35: Cert handshake failed. Fatal error. UnityTls error code: 7 don’t despair, this is a known issue with older base (FROM) images including an expired root authority certificate. You can fix this by updating to a newer base image version (e.g. ubuntu:22.04), and running update-ca-certificates , add this to your Dockerfile:

  Copy

  FROM ubuntu:22.04
  
  RUN apt-get install -y ca-certificates && \
      apt-get clean && \
      update-ca-certificates

Always make sure you are working with a functioning server build.

• Before assuming an issue is related to the custom Dockerfile, ensure your Unity server build can be started, and that the build process in Unity didn’t throw any exceptions or errors.

Always test locally before uploading.

• Testing your image locally will save you lots of time while waiting for the upload to finish. It’s also entirely free ✨ as it doesn’t require any Edgegap resources.

• When testing locally, make sure to set your internal port correctly:

  Copy

  docker run \
    -p 7777/udp \
    -e ARBITRIUM_PORTS_MAPPING='{"ports":{"gameport":{"internal":7777}}}' \
    'registry.edgegap.com/<repository>:<tag>'

Make sure you’ve got the basics down. Every Dockerfile needs a few essential commands:

• FROM {image} is your base image, for Unity projects we usually use a long-term supported Linux, but any Linux-based base image will do. These are usually public images stored on dockerhub. Dockerfile reference here. Dockerfile reference here.

• COPY {source} {destination} to copy your linux server build from your host machine inside the image, so you can start it later on. Dockerfile reference here.

• USER {user} should follow after a useradd (ubuntu) command or equivalent, it’s best not to run everything as root to be on the safer side. Dockerfile reference here.

• CMD {command} will be the last line, most likely calling a StartServer.sh or some kind of startup script to make sure your server initializes correctly once everything is set up. Dockerfile reference here.

• do NOT use VOLUME - you will not be able to mount any local storage this way on Edgegap, consider our Endpoint Storage feature instead and use an S3 bucket, see Endpoint Storage.

Delay declaration of parameters until latest possible moment. Configurability > composability due to long server build times.

• Scenario: you need to define parameters like deployment stage, version, game mode, map, player count per server, backup frequency, or similar.

• Bad solution: creating a separate image for every combination of your parameters. You will spend all of your time rebuilding the images with very little benefits from this approach.

• Better solution - substitute configuration parameters just in time:

  1. deployment parameters - supplied just before the deployment is made - matchmaking selectors passed as environment variables, or your custom session management system passing environment variables at deployment time,

  2. version parameters - shared for all deployments on an app version - deployment stage, artifact tag, third party secrets and endpoints, and similar; then

  3. one single image - contains and loads all configuration options when launched.

Do NOT rely on EXPOSE docker command to handle port mapping.

• The EXPOSE command is intended to signal to the user of your image which ports are to be opened, however due to security reasons we can’t let you define 1:1 port mappings on fixed ports. You may supply this argument but it will be ignored during deployment on Edgegap. Configure your port mapping through our Dashboard or API - see 🏷️ App Versions.

Do NOT run databases on Edgegap deployments.

• Edgegap deployments are not intended for long-running processes and may be terminated after a long period of runtime without prior notice. A database (even if distributed) running in this manner may be terminated and result in an irreversible loss of data. If you need a database, please consider a third party DBaaS.

• Consider using our Managed Clusters for hosting databases and long running services.