Docker configuration

Use this guide to configure Nakama when running with Docker. Bind a local folder into the container, place a YAML config there, and reference it in docker-compose.yml so the server reads it at startup. The config file uses the same YAML schema described in the Server configuration guide, Docker only changes where the file lives and how it’s passed to Nakama.

This guide assumes you’ve followed the steps in Install Nakama with Docker Compose.

Step 1: Mount a host directory as a Docker volume #

  1. Open your docker-compose.yml file in your preferred text editor.
  2. Edit the nakama:volumes: entry to specify your volume. For example, to map a local ./data directory to /nakama/data inside the container:
1
2

volumes:
  - ./data:/nakama/data

This maps the local ./data directory to the /nakama/data path inside the Nakama container.

  1. Save the file and restart your Docker services:
1
2

docker compose restart
docker compose up

Step 2: Create a Nakama configuration file #

Create a custom configuration file, for example my-config.yml, and place it in the /data folder you mounted.

PostgreSQL example #

my-config.yml

1
2
3
4
5
6
7
8

name: nakama1
database:
  address:
    - "postgres:localdb@postgres:5432/nakama"
logger:
  level: DEBUG
session:
  token_expiry_sec: 7200

CockroachDB example #

my-config.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

name: nakama1
database:
  address:
    - "root@cockroachdb:26257"
logger:
  level: DEBUG
session:
  token_expiry_sec: 7200
metrics:
  prometheus_port: 9100

Step 3: Point Nakama to the config in docker-compose.yml #

Edit the Nakama service’s entrypoint to include the --config flag that references the file in /nakama/data:

1
2
3
4
5
6
7

nakama:
  entrypoint:
    - "/bin/sh"
    - "-ecx"
    - >
      /nakama/nakama migrate up --database.address postgres:localdb@postgres:5432/nakama &&
      /nakama/nakama --config /nakama/data/my-config.yml

If using CockroachDB, replace postgres:localdb@postgres:5432/nakama with root@cockroachdb:26257.

Step 4: Restart Docker containers #

Save the file and restart for the changes to take effect:

1
2

docker compose restart
docker compose up