t1k:nakama:config

Field	Value
Module	`base`
Version	`1.6.2`
Effort	`low`
Tools	—

Keywords: config, configuration, docker, environment variables, nakama, yaml

How to invoke

/t1k:nakama:config

Nakama Configuration

Overview

Nakama uses config.yml for server configuration. The project uses a template (config.yml.tmpl) with environment variable substitution. Runtime env vars are passed to Go plugin code via runtime.RUNTIME_CTX_ENV.

Key Patterns

Config Template (config.yml.tmpl)

runtime:
  env:
    - GAMEPLAY_GRPC_ADDR=gameplay:9550
    - GAMEPLAY_API_KEY=${GAMEPLAY_API_KEY}
    - MOCK_GAMEPLAY_ENDPOINTS=${MOCK_GAMEPLAY_ENDPOINTS:-false}
    - FIREBASE_AUTH_ENABLED=${FIREBASE_AUTH_ENABLED:-false}
    - ORION_CONTRACTS_DIR=/nakama/contracts

Reading Env Vars in Go

env, _ := ctx.Value(runtime.RUNTIME_CTX_ENV).(map[string]string)
addr := env["GAMEPLAY_GRPC_ADDR"]

Key Environment Variables

Variable	Purpose	Default
`MOCK_GAMEPLAY_ENDPOINTS`	Enable mock mode	`false`
`GAMEPLAY_GRPC_ADDR`	Gameplay gRPC address	`gameplay:9550`
`GAMEPLAY_API_KEY`	Service auth key	(required)
`FIREBASE_AUTH_ENABLED`	Enable Firebase auth	`false`
`FIREBASE_PROJECT_ID`	Firebase project ID	(required if Firebase)
`ORION_CONTRACTS_DIR`	Contract files path	`/nakama/contracts`
`ORION_MOCK_DATA_DIR`	Mock data override	(derived from contracts)

Docker Setup

services:
  nakama:
    build: .
    environment:
      - MOCK_GAMEPLAY_ENDPOINTS=true
    volumes:
      - ./modules:/nakama/data/modules
    depends_on:
      - postgres

Gotchas

config.yml.tmpl uses shell-style ${VAR:-default} substitution — NOT Go templates
Env vars in runtime.env are a flat list of KEY=VALUE strings, not a map
Docker must mount the built .so file into /nakama/data/modules/
Postgres connection is configured in the Nakama config, not in Go plugin code
The contracts directory must be mounted if using contract-based mock resolution
YAML template expansion order: Environment variables in config.yml.tmpl are expanded at container startup, not build time. Missing vars = empty strings, not errors.
Docker volume mounts: Config files mounted as volumes override the container’s built-in config. Ensure mount paths match Nakama’s expected paths.
runtime.env ordering: Variables are processed in order. Later entries can reference earlier ones but not vice versa.

Checklist

All required env vars documented and set
config.yml.tmpl updated when adding new env vars
Docker volumes mount .so file and contract dirs correctly
Sensitive vars (API keys) not hardcoded — use env vars or secrets
Default values provided where sensible (:-default syntax)