Migrating from open source Nakama to Heroic Cloud

Moving from self-hosted Nakama to Heroic Cloud doesn’t require changes to your server code or client SDKs. Nakama Enterprise on Heroic Cloud is fully compatible with open source Nakama at the API and runtime level. The main things to plan for are custom forks, data migration, and production cutover — this page covers each.

Custom server code, compatibility, and forks #

Heroic Cloud fully supports your runtime code and custom logic — whether written in Lua, Go, or TypeScript — without any changes needed to your server code or client SDKs when moving from a self-hosted open source Nakama deployment to Nakama Enterprise on Heroic Cloud.

Your game will transparently benefit from the additional resilience, scalability, and enterprise features that Nakama Enterprise on Heroic Cloud provides.

To deploy your custom code on Heroic Cloud, you package it using the builder pipeline. The builder connects to your Git repository, compiles your server code against a specific Nakama version, and produces a container image for deployment. See Builders and repository setup for how to structure your repository and set up the pipeline.

Forks of Nakama open source aren’t supported on Heroic Cloud. You must use an official Nakama release image. Heroic Cloud doesn’t support custom-compiled or modified Nakama binaries.

If you’ve made modifications directly to the Nakama source code in your fork, you’ll need to migrate that logic to the Go runtime plugin system instead. Nakama’s Go runtime allows you to extend and customize Nakama behavior through a supported plugin interface without modifying the core binary.

Custom DNS records #

Your deployment hostname will always be provided by Heroic Cloud. Custom DNS records or imported DNS records of your choice aren’t supported, due to domain verification rules around SSL certificates.

When you’re ready to switch over your Nakama instance to the Heroic Cloud hosted instance, update your client code to use the DNS records provided by Heroic Cloud.

Data migration #

Heroic Cloud can assist with migrating your game data from a self-hosted deployment. Contact Heroic Labs to arrange migration — the process will depend on your needs:

  • One-off data migration. The quickest and easiest option. Your data is exported and imported as a one-off operation.
  • Live data migration. For migrating between your hosted PostgreSQL-compatible database and Heroic Cloud while your game is live. Database limitations apply.

Contact Heroic Labs to arrange migration: support@heroiclabs.com

See also #