Nakama deployments

A Nakama deployment is your complete game backend. When you create one, Heroic Cloud provisions the entire dedicated stack. You don’t configure individual components or manage the underlying infrastructure. Everything below is set up, maintained, and operated by Heroic Cloud:

Creating a deployment #

When creating a Nakama deployment, you make four permanent choices:

1. Deployment type is either development or production. This is a permanent choice — it can’t be changed later without recreating the deployment entirely, which will require manual data migration. See Scaling for the differences.
2. Deployment zone is the region where your instance will run. Choose a zone close to your players to minimize latency. The zone can’t be changed after creation.
3. Instance name must be unique and becomes part of your DNS hostname. Names may contain dashes (for example, mygame-nakama-prod). Once set, the instance name can’t be changed.
4. Nakama version follows semantic versioning, with an -rN suffix for Heroic Labs revisions. Unless the support team advises otherwise, select the highest revision available. See Nakama versions and upgrades.

Plan your naming convention and region strategy before creating production deployments.

Deployment zones #

Heroic Cloud runs on both GCP and AWS.

GCP regions:

AWS regions (available on request — see below):

If you need to run on AWS specifically, contact Heroic Labs and explain why your deployment requires that cloud provider. Custom DNS records aren’t supported; your deployment will always use a Heroic Cloud-managed domain.

Nakama versions and upgrades #

When you create a builder or trigger a build, you select the Nakama version to compile against. The version is baked into the image, so upgrading Nakama means building a new image against the newer version and deploying it.

Run different Nakama versions across environments. For example, your development instance might run a newer version while production stays on the current stable release until you’ve validated the upgrade in QA.

Version strings #

Versions in the builder look like 3.38.0-r4. Each part of that string tells you something different:

Revisions #

A revision is a hot patch built on top of an already-released Nakama version. Heroic Labs builds one when a customer reports a problem worth fixing before the next official release. Moving from 3.38.0-r2 to 3.38.0-r4 picks up those fixes without changing the Nakama version you’re on.

Revisions carry three guarantees:

• Always backwards compatible: A revision changes internal code only. Interfaces, function signatures, and configuration stay the same, so your server code and client SDKs need no changes.
• Cumulative: Revision r4 includes everything in r2 and r3, so skipping intermediate revisions is safe.
• Always rolled into the next release: Anything fixed in a revision ships in the next official Nakama version. Upgrading from 3.38.0-r4 to a later version never loses a fix you gained from a revision.

Select the highest revision available for the Nakama version you’re targeting, unless the Heroic Labs support team has told you otherwise. Rebuild against the new version, then deploy the resulting image. Nothing else changes.

Revisions don’t get their own release notes, because each one targets a narrow set of reported issues. To find out what changed between two revisions, ask Heroic Labs support.

Version support policy #

Heroic Cloud officially supports the last 4 official released versions (not including revisions) of Nakama. For example, if the current latest version is 3.37, versions 3.33 through 3.37 are fully supported. Older versions may continue to work because Nakama doesn’t break backwards compatibility, but they’re unsupported by Heroic Cloud.

Database migrations #

On Heroic Cloud, each Nakama deployment runs nakama migrate up on startup, before the server process starts, so any pending schema migrations are applied automatically. In practice this means a new Nakama version’s migrations are applied on deploy. If the schema is already up to date, nothing happens. Note that downgrades are disallowed as they’ll cause data loss. Please contact the Heroic Labs support team to assist with the downgrading Nakama to an earlier version.

Downgrading Nakama #

Version downgrades require intervention by the Heroic Cloud team as automated downgrading could cause issues with data integrity (for example, dropping database tables). If you need to roll back to an older Nakama version, contact Heroic Labs (support@heroiclabs.com).

Connecting your game client #

Each deployment gets a unique hostname in the format {instance-name}.{zone}.heroiclabs.com on port 443 (TLS encrypted). You also get two authentication keys:

• Server key is used by game clients to authenticate with the Nakama server. Anyone with this key can connect to your backend as a client. Treat it as a shared secret between your game client and the server.
• Runtime (HTTP) key is used for server-to-server API calls. This key grants higher-privilege access than the server key, including the ability to call administrative runtime functions. It should never be included in game client code.

Both keys are sensitive credentials. Leaking the server key means anyone can connect to your backend. Leaking the runtime key means anyone can call administrative APIs. For this reason, access to these keys is gated behind the Secrets permission. Only users and service users with this permission can view or copy them. See Access control.

SDK code snippets are available for JavaScript, C# / Unity, and Godot. For full client SDK guides, API references, and connection examples, see the Nakama documentation.

Nakama Console #

Each deployment includes a separate management console for inspecting players, storage objects, leaderboards, matches, and other Nakama features directly. This is useful for debugging, customer support, and verifying that your server logic is working correctly.

Deploying images #

Deployments use a rolling update. Nakama nodes restart one at a time, and the load balancer sends new connections only to the nodes that aren’t restarting.

Deploy downtime #

A rolling update only avoids downtime when another node stays up to serve traffic. Whether a deploy interrupts your players depends on how many Nakama nodes the deployment runs:

Node count follows CPU allocation. Development deployments are fixed at a single node and can’t be scaled. Production deployments also start at a single node, then split into two nodes on separate physical VMs once you allocate at least 2 vCPUs.

That threshold is where deploys stop causing downtime. Beyond 2 vCPUs, the cluster topology depends on capacity at the time of scaling. See Scaling.

Multiple nodes keep the deployment reachable, but they don’t preserve individual connections. Clients attached to a restarting node lose their WebSocket connection and have to reconnect. See Rolling reboot for what clients need to handle, and Authoritative multiplayer and reboots for carrying live matches across a rollout.

Failed deploys #

If a deploy fails (for example, if the new image crashes on startup), the rolling update stops and the healthy Nakama instances continue serving traffic. Deploy a known-good image to recover.

CrashLoopBackOff #

If a Nakama instance crashes on startup, the system enters a CrashLoopBackOff state: the instance is killed, restarted, crashes again, and so on, with increasing delays between restart attempts. This prevents a crash from consuming resources in a tight loop.

You don’t need to wait for the system to settle before taking action. Update your deployment configuration, deploy a different image, or make other changes while CrashLoopBackOff is in progress.

A 60-minute timeout applies before the operation is marked as failed. If the deployment hasn’t stabilized within 60 minutes, deploy a known-good image to recover.

Common causes of CrashLoopBackOff include misconfigured environment variables, a startup crash in your custom server code, or an incompatible Nakama version. Check the deployment logs first to identify the cause.

Runtime variables and Nakama configurations #

A deployment has two separate places to put settings, and they aren’t interchangeable. Which one you pick depends on a single question: who reads the value, your code or Nakama’s code?

The secret variants change who can view a value, not who reads it. A runtime secret variable is still read only by your code, and a secret configuration is still read only by Nakama.

Runtime variables #

Runtime variables are environment variables injected into your Nakama processes. Nakama passes them to your custom modules as the runtime environment, which your code reads from the context object. See Server framework for how to read them in Go, TypeScript, and Lua.

Use runtime variables for values your own code needs: feature flags, endpoints for third-party services, and anything that differs between your development, QA, and production deployments. Mark a variable as secret when the value is a credential, so only users with the Secrets permission can read it back.

Changing a runtime variable requires a rolling reboot to take effect.

Nakama configurations #

Nakama configurations are the server settings that control how the Nakama process itself behaves, from session and socket tuning to integrations like Satori. If a setting appears in the server configuration reference, it belongs here. That includes every iap.*, google_auth.*, and social.* credential, because Nakama’s built-in purchase validation and social sign-in read them directly.

Manage configurations either through the dashboard or by committing a YAML file to your repository.

Values that are too sensitive to sit in the dashboard or a repository go in secret configurations. These are stored separately but merged into the rest of your configuration at startup, so Nakama sees one unified configuration while the sensitive values stay protected.

Changing a configuration value requires a rolling reboot to take effect, since the Nakama processes need to restart with the new settings. See Rolling reboot for details.

Deleting a deployment #

Deployments can’t be paused, stopped, or temporarily disabled. A deployment is either provisioned or it isn’t.

The resources stay allocated on the cloud provider whether or not the deployment serves traffic. That includes the database disk holding your data, which can’t be released without destroying it.

Nothing in the dashboard or the API suspends a deployment, and service users can’t create or delete deployments at all. See Use the Heroic Cloud API.

To free up a deployment you need only part of the time, export it, delete it, and recreate it later:

1. Export the database from the Data Export tab while the deployment still exists. Deletion is permanent and takes the data with it, so export first. See Export your Nakama database.
2. Delete the deployment. Heroic Cloud meters resource usage daily, so charges stop accruing the day after you delete it. See Billing.
3. Recreate the deployment when the work resumes. Redeploy your image, then restore the export if you want the previous data.

Provisioning a new deployment takes time, and a recreated one starts empty: its runtime variables, Nakama configurations, and resource permissions all need setting up again.

Cycling a deployment is worth it for environments that sit idle for weeks at a time. For anything you touch most weeks, leaving it running usually costs less overall.

Reusing a deployment name #

Instance names only need to be unique among the deployments that currently exist in your organization, not across every deployment you have ever created. Deleting a deployment releases its name, so an environment you cycle on and off can use the same name every time.

The name is released when the deletion finishes, not when you request it. Deletion runs as a background operation, and a recreate attempted while it’s still in progress fails because the old deployment still holds the name.

What doesn’t carry over is the deployment’s identity underneath. Each deployment is provisioned with a four-character suffix appended to its instance name, generated fresh every time. That suffix identifies the dedicated stack: the database, the compute instances, and the DNS record.

Because the suffix is part of the DNS record, the hostname changes on every recreate, even when the instance name stays the same:

1
2

mygame-nakama-prod-42bc.us-east1.heroiclabs.com    # original deployment
mygame-nakama-prod-9f07.us-east1.heroiclabs.com    # same instance name, recreated after deletion

Anything pinned to the old hostname needs repointing after a recreate: game clients, server-to-server integrations, monitoring checks, and any configuration you manage as code. Read the hostname back from the dashboard or the API once provisioning completes.

Delete protection #

Delete protection prevents accidental deletion of the deployment. It’s enabled by default on production deployments. When enabled, the deployment can’t be deleted until protection is explicitly disabled.

To delete a protected deployment, disable Delete protection in the deployment settings, then proceed with deletion.

Disabling delete protection requires the Delete permission on the deployment. If you don’t have access, contact your organization owner or Heroic Labs support.

Rolling reboot #

Restarts each Nakama instance one at a time, maintaining availability throughout. Use this after runtime variable changes or to recover from an unhealthy state. Scaling changes also trigger a rolling reboot automatically.

During a rolling reboot, Heroic Cloud routes new incoming connections only to nodes that aren’t being restarted. Existing connections on a restarting node drop when that node shuts down.

Clients must implement reconnection logic. No mechanism exists to transparently move an existing WebSocket connection from one Nakama node to another. When a client’s connection drops during a reboot, the client is expected to reconnect to the server. Standard SDK reconnection patterns are sufficient for this.

The duration of a rolling reboot depends on the configured grace period shutdown in your Nakama configuration. The grace period is the time Nakama waits before forcefully shutting down to allow in-flight operations to complete. The default is approximately 10 seconds. If you’ve configured a longer grace period (for example, 60 minutes for authoritative matches), each node takes that long to cycle. Rolling reboots can’t be cancelled.

Authoritative multiplayer and reboots #

If you have authoritative server-side match logic running inside Nakama and a node reboots, in-flight matches on that node will be interrupted. To handle this gracefully in Nakama on Heroic Cloud, use two Nakama features in combination:

1. Match terminate signal in your match handler: when triggered, your logic can create a new match on another node and forward the new match connection information to the clients, allowing them to reconnect transparently.
2. Grace period shutdown configuration: gives in-flight matches enough time to complete the migration before the node shuts down.

Heroic Cloud systems are aware of both the match terminate signal and the grace period shutdown configuration. New connections are automatically routed only to non-rebooting nodes during the process. This combination allows you to transparently migrate match state between nodes on reboot.

Scaling #

Scaling is entirely platform-managed. The first step — going from 1 CPU to 2 CPUs — always results in high availability with two Nakama nodes. Beyond 2 CPUs, the cluster topology depends on availability and capacity at the time of scaling.

Nakama nodes and the database scale independently. Scale up or down at any time. Scaling triggers a rolling reboot.

Scale the database up but not down — a minimum CPU count is tied to the disk provisioned for that instance. Plan your database tier carefully.

See Scaling for tiers, costs, and timing.

Operations queue #

When you trigger an action that takes time to complete — such as deploying an image, scaling a deployment, triggering a build, or running a data export — it enters the operations queue. Operations run one at a time per resource. If you trigger a second operation while the first is still running, it queues behind it.

Each operation shows its current status (pending, in progress, completed, or failed), who triggered it, and when. If an operation fails, the resource remains in its previous state — retry or take corrective action.

Heroic Cloud sends email notifications when operations complete successfully or fail, so you don’t need to watch the queue for results.

Monitoring #

Built-in time-series charts cover load balancer request count (by HTTP status code), Nakama CPU and memory utilization (per node), database CPU utilization, and database query load. A top database queries view surfaces the most expensive SQL queries with an impact indicator.

These built-in metrics are good for day-to-day monitoring. For custom dashboards, alerting, and long-term retention, use the metric exporting add-on to feed data into your own Prometheus/Grafana stack. See Metric exporting.

Logs #

Deployment logs are available in UTC with full-text search, severity filtering, and date range selection. Logs can be exported on demand. For continuous log shipping to your own infrastructure, see Log exporting.

Individual log lines are truncated at 5KB per line. If your game module produces log output longer than this (for example, large JSON payloads or verbose stack traces), the line will be cut off. Structure your logging to stay within this limit.

Data export #

Download a complete snapshot of your PostgreSQL database at any time. This is your data. Only one export can run at a time, and download links expire. See Data exporting for the full guide.

Audit #

Every user action on the deployment is logged: who deployed an image, who changed configuration, who triggered a reboot. This is scoped to the individual deployment. For the organization-wide audit log, see Audit log.

Billing #

Nakama deployment usage is measured at intervals throughout the day. The highest CPU count recorded during a given day is used to calculate that day’s charge. These daily charges accumulate and are invoiced on the first of the following month. See Billing for billing details.

Permissions #

Each deployment has its own permissions that control who can view, edit, deploy, delete, export, scale, and access secrets. Resource-level permissions override title-level and organization-level settings. This is how you lock down production while keeping dev and QA open. See Access control.

See also #

• Nakama documentation for SDK guides, API reference, and server framework.
• Scaling for resource tiers, costs, and timing.
• Builders and repository setup for deploying custom server code.
• Set up CI/CD for Nakama for automating builds and deploys.
• Operations overview for monitoring and observability tools.
• Access control for locking down production deployments.