Skip to main content

Upload builds and configure deployments

This doc will cover the process and components involved in uploading your server build and deploying it on Hathora. The most relevant entities for this are Hathora’s Builds and Deployments.

Uploading builds to Hathora​

Builds in Hathora are meant to be mapped directly to server builds from your existing CI/build pipeline. You can use buildTag or override a unique buildId to map your server builds to external systems.

Build Upload Format​

You will need to upload a tarball (.tgz or tar.gz file) that contains a Linux server build and a Dockerfile in the root of the Tarball.

tar.gz file
├── Dockerfile
└── <...your server build/project files>

Under the hood, we use Docker containers to offer a flexible and reliable environment for your game servers. By using containers, you can easily customize the runtime environment for your server, ensuring it’s lightweight, portable, and consistent.

  • Dockerfile: Target OS, install dependencies, start the game server init script
  • init.sh: Connect server with Hathora metadata (connection info, etc)

To upload your build file, you can use our Hathora CLI tool to deploy from your terminal or a script. Otherwise, you can drag and drop it directly in the Hathora Console UI.

Integration with your CI system​

Builds in Hathora are designed to work seamlessly with your existing system, here are some useful tips:

  • Support for TeamCity, Jenkins, GitHub Actions, and custom CI pipelines are all well support. For examples for setup, check out this guide.
  • Global builds: all builds can easily be reused across multiple applications in Hathora, enabling flexible environment setups, while also avoiding duplicate uploads.
  • Custom Build Ids and Tags: you to assign custom buildIds so you can use your existing CI buildIds in Hathora. Additionally, you can tag your builds using buildTag to make it easy to organize/filter your builds.

Here’s how to push a build using the Hathora CLI:

hathora build create --file path/to/your-build.tar.gz

For detailed instructions on connecting CI/CD systems, refer to our CI/CD guide.

Configuring deployments​

Once you've successfully uploaded a server build onto Hathora, the next step is to create a deployment so you can use it.

Create a Deployment (build + configuration)​

A deployment is used to define the runtime configurations for a build. Deployments are used to:

  • Configure settings like transport type, port, and CPU/Memory profile
  • Define custom environment variables
  • Select a server build to use
  • Optionally assign a custom deploymentTag for your deployment

Rolling Upgrades​

New deployments do not interrupt running processes, ensuring a smooth transition with zero downtime. This allows you to roll out new deployments confidently, even in live production environments.

Eager Caching​

note

Eager caching is an advanced feature and only available for Pro and Enterprise customers. Learn more about our tiers.

Eager caching enables near-instant process boot times (under than 3 seconds). Hathora proactively pushes new deployments and their corresponding builds to all nodes in your fleet. Eager caching only applies to the latest deployment and pushes to all available nodes in your fleet at the time of deployment.

Running server instances​

Once you have your game server deployed on Hathora, it’s easy to spin up processes to host a match or game session. You can call the CreateRoom endpoint with a target region and Hathora will return a host:port to connect to.

note

Hathora’s API endpoints are documented here and can be used from our various SDKs(Java, Typescript, Go, Unreal, Unity/C#, Godot)

Activating a Deployment​

By default, the createRoom API uses the latest deployment for an application. Alternatively you can specify a deploymentId in the createRoom request to quickly switch between deployed versions during deployment and testing.

note

Only the latest deployment is eagerly cached. Learn more here