Deploy and Host Nakama Server on Sealos

Nakama is an open-source game server for realtime multiplayer, player accounts, social systems, and live operations. This template deploys Nakama v3.39.0 with a managed PostgreSQL database on Sealos Cloud.

About Hosting Nakama

Nakama runs as a single game-server node with built-in HTTP API, realtime socket support, gRPC endpoints, and an embedded admin console. It stores users, sessions, leaderboards, groups, storage objects, chat messages, and other game data in PostgreSQL.

The Sealos template provisions PostgreSQL 16.4.0, creates the nakama database, runs Nakama schema migrations, and starts the server after the database is ready. It also generates session, runtime, console, and socket keys for each deployment.

Nakama Console is exposed as the primary web entry. The HTTP API is exposed on a separate URL for REST and WebSocket clients, while public gRPC ingress can be enabled when your client stack needs direct gRPC access.

Common Use Cases

• Realtime Multiplayer Games: Handle realtime sessions, matchmaking, authoritative matches, and game server logic.
• Player Identity and Accounts: Use device, email, social, or custom authentication flows for players.
• Social Game Systems: Add friends, groups, chat, parties, notifications, and user metadata.
• Leaderboards and Tournaments: Build competitive rankings, seasonal challenges, and event-based scoring.
• Live Operations Dashboards: Inspect players, storage, matches, runtime modules, and service metrics through Nakama Console.

Dependencies for Nakama Hosting

The Sealos template includes all required runtime dependencies: Nakama Server and PostgreSQL. No separate console image is required because Nakama Console is embedded in the Nakama binary.

Deployment Dependencies

• Official Nakama Documentation - Product documentation and development guides
• Nakama GitHub Repository - Source code and release notes
• Nakama Docker Installation Guide - Official container deployment reference
• Nakama Client Libraries - SDKs for Unity, Unreal, Godot, JavaScript, and more

Implementation Details

Architecture Components:

This template deploys these services:

• Nakama Server: StatefulSet running heroiclabs/nakama:3.39.0 with persistent /data storage for runtime modules.
• PostgreSQL Database: KubeBlocks PostgreSQL 16.4.0 cluster for persistent Nakama data.
• PostgreSQL Init Job: Creates the nakama database idempotently before the server starts.
• Nakama Console Ingress: Primary web entry that routes to Nakama Console on port 7351.
• Nakama HTTP API Ingress: Secondary endpoint for /v2 REST API and /ws realtime WebSocket traffic on port 7350.
• Optional gRPC Ingresses: Public routes for Nakama gRPC (7349) and console gRPC (7348) when enable_grpc is enabled.

Configuration:

Nakama starts only after PostgreSQL is reachable and the target database exists. A migration init container runs nakama migrate up before the main server starts, then health probes use nakama healthcheck for startup, readiness, and liveness checks.

The primary resource profile is tuned to the smallest validated Sealos tier for this template: 100m CPU and 128Mi memory for the Nakama container. PostgreSQL uses the standard database profile: 500m CPU and 512Mi memory.

Login and Access:

Nakama Console requires the console credentials configured during deployment:

• Username: value of console_username (default admin)
• Password: value of console_password

Player accounts are not created from the console login screen. Game clients create or authenticate player accounts through Nakama APIs such as device authentication at /v2/account/authenticate/device?create=true, using the configured socket/server key as Basic Auth username.

License Information:

Nakama is licensed under Apache-2.0. This Sealos template is also provided under Apache-2.0.

Why Deploy Nakama on Sealos?

Sealos is an AI-assisted Cloud Operating System built on Kubernetes that unifies the application lifecycle from deployment to operations. By deploying Nakama on Sealos, you get:

• One-Click Deployment: Deploy Nakama and PostgreSQL from the App Store without writing Kubernetes YAML.
• Managed Public URLs: Get HTTPS URLs for the console and API automatically.
• Persistent Data: Store player, leaderboard, group, and storage data in managed PostgreSQL.
• Easy Customization: Adjust credentials, resource limits, and optional gRPC exposure from the deployment form or Canvas.
• Kubernetes Foundation: Run on a Kubernetes-based platform without managing cluster primitives directly.
• Pay-As-You-Go Resources: Start from a small validated footprint and scale resources as player traffic grows.

Deployment Guide

1. Open the Nakama Server template and click Deploy Now.
2. Configure the parameters in the popup dialog:
   • Console Username: Admin username for Nakama Console. The default is admin.
   • Console Password: Password for the console user. Set a strong value and save it securely.
   • Enable gRPC: Optional. Enable only if your clients need public gRPC endpoints.
3. Wait for deployment to complete. It typically takes 2-3 minutes because PostgreSQL must initialize before Nakama starts.
4. Open the primary application URL to access Nakama Console.
5. Log in with the configured Console Username and Console Password.
6. Use the API URL for game clients:
   • HTTP API: https://<api-url>/v2/...
   • WebSocket: wss://<api-url>/ws
   • gRPC: Use the generated gRPC URLs only when enable_grpc is enabled.

Configuration

After deployment, manage Nakama through:

• Nakama Console: Inspect users, groups, storage, matches, leaderboards, notifications, API Explorer, and runtime modules.
• Canvas AI Dialog: Describe configuration changes and let Sealos apply updates.
• Resource Cards: Adjust StatefulSet resources, Ingress routes, and PostgreSQL settings from the Canvas.
• Runtime Modules: Mount or upload Lua, JavaScript, or Go runtime modules under /data/modules as needed.

Console Login

The console does not provide public self-registration. Use the console credentials configured during deployment. If you lose the password, update console_password in the Nakama StatefulSet arguments or redeploy with a new password.

Client Authentication

Nakama supports player registration through API flows such as device authentication, email authentication, and social provider authentication. For a basic device-auth smoke test, game clients call:

curl -X POST "https://<api-url>/v2/account/authenticate/device?create=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(printf '<server-key>:' | base64)" \
  -d '{"id":"unique-device-id","vars":{}}'

Replace <server-key> with the generated server key for your deployment. The template generates this value automatically as server_key; view it from the rendered deployment arguments or the Nakama StatefulSet NAKAMA_SOCKET_SERVER_KEY environment variable if you need to run manual API tests.

Scaling

Start with the default validated resource profile for development and small tests. To scale your Nakama deployment:

1. Open the Canvas for your deployment.
2. Click the Nakama StatefulSet resource card.
3. Increase CPU and memory to the next Sealos resource tier if player traffic, runtime modules, or match logic require more capacity.
4. Click the PostgreSQL resource card if database load becomes the bottleneck.
5. Apply the changes and verify readiness in Nakama Console.

For production multiplayer games, benchmark with representative concurrent users, match logic, runtime modules, and API traffic before choosing final resource limits.

Troubleshooting

Common Issues

Nakama Console login fails

• Cause: Incorrect console username or password.
• Solution: Use the credentials configured during deployment. The default username is admin, but the password is whatever you entered in the deployment form.

API returns Server key invalid

• Cause: The client is using the wrong Basic Auth username.
• Solution: Use the deployment's server key as the Basic Auth username and an empty password.

Database initialization takes longer than expected

• Cause: PostgreSQL is still starting or creating the nakama database.
• Solution: Wait a few minutes. The init containers are designed to wait for database readiness and run migrations automatically.

gRPC client cannot connect

• Cause: Public gRPC ingress was not enabled or the client is using the HTTP API URL.
• Solution: Redeploy or update the template with enable_grpc enabled, then use the generated gRPC endpoint.

Getting Help

• Nakama Documentation
• Nakama GitHub Issues
• Heroic Labs Forum
• Sealos Documentation
• Sealos Discord

Additional Resources

• Nakama Getting Started
• Nakama Runtime Code
• Nakama API Reference
• Nakama Console Guide

License

This Sealos template is provided under Apache-2.0. Nakama itself is licensed under Apache-2.0.