

Configuration¶

A YAML configuration file configures many aspects of how your Nakama server runs. You can run Nakama without specifying a configuration file and rely on the the default settings instead.

Specifying a config file¶

You can specify a configuration file at run-time using --config flag.

nakama --config my-special-config.yml

If you are running Nakama via Docker-Compose, you'll need to bind a folder in your machine so that it's available in Docker. Follow this guide to setup folder binding.

Common properties¶

There are a few configuration properties that need to be changed in most environments. The full list of configurations is at the bottom of the page.

Parameter	Description
`name`	Nakama node name (must be unique) - It will default to `nakama-xxxx` where `xxxx` is 4 random characters.
`data_dir`	An absolute path to a writeable folder where Nakama will store its data, including logs. Default value is the working directory that Nakama was started on.
`runtime.path`	Path of modules to scan and load. Defaults to `data_dir/modules`.
`database.address`	List of database nodes to connect to. It should follow the form of `username:password@address:port/dbname` (`postgres://` protocol is appended to the path automatically). Defaults to `root@localhost:26257`.
`socket.server_key`	Server key to use to establish a connection to the server. Default value is `defaultkey`.
`session.encryption_key`	The encryption key used to produce the client token. Default value is `defaultencryptionkey`.
`runtime.http_key`	Key is used to protect the server's runtime HTTP invocations. Default value is `defaultkey`.

Production settings

You must change the values of socket.server_key, session.encryption_key and runtime.http_key before you deploy Nakama to a live production environment.

Follow the production settings deployment guide for more information.

Server Configuration¶

Nakama has various configuration options to make it as flexible as possible for various use cases and deployment environments.

Nakama ships with sane default values for all config options, therefore you'll only need to override a subset of the options. You can also setup your own config file, and override the values in the config file via command-line flags. For instance, to override Runtime Path:

nakama --runtime.path /tmp/my-modules

If fields are not specific, default values will be used. For more information on how to override flags, have a look at the server command-line page.

Override configuration

Every configuration option can set from a config file, as a command line flag or both where the command-line argument takes precedence and will override the configuration values.

Parameter	Flag	Description
`name`	`name`	Nakama node name (must be unique) - It will default to `nakama-xxxx` where `xxxx` is 4 random characters. This name is also used in the log files.
`data_dir`	`data_dir`	An absolute path to a writeable folder where Nakama will store its data, including logs. Default value is the working directory that Nakama was started on.

Log¶

Nakama produces logs in JSON format so various systems can interact with the logs. By default they are written to log files inside data_dir/logs folder.

Parameter	Flag	Description
`stdout`	`log.stdout`	Redirect logs to console standard output. The log file will no longer be used. Default is `false`.
`verbose`	`log.verbose`	Turn on verbose logging. You'll see a lot more logs including debug-level information. This is useful for debugging purposes. Default is `false`.

Database¶

Nakama requires a CockroachDB server instance to be available. Nakama creates and manages its own database called nakama within the CockroachDB database.

Parameter	Flag	Description
`address`	`database.address`	List of database nodes to connect to. It should follow the form of `username:password@address:port/dbname` (`postgres://` protocol is appended to the path automatically). Defaults to `root@localhost:26257`.
`conn_max_lifetime_ms`	`database.conn_max_lifetime_ms`	Time in milliseconds to reuse a database connection before the connection is killed and a new one is created.. Default value is 60000.
`max_open_conns`	`database.max_open_conns`	Maximum number of allowed open connections to the database. Default value is 0 (no limit).
`max_idle_conns`	`database.max_idle_conns`	Maximum number of allowed open but unused connections to the database. Default value is 0 (no limit).

Database addresses

You can pass in multiple database addresses to Nakama via command like:

nakama --database.address "root@db1:26257" --database.address "root@db2:26257"

Runtime¶

Options related to Lua-based runtime engine.

Parameter	Flag	Description
`env`	N/A	List of Key-Value properties that are exposed to the Runtime scripts as environment variables.
`path`	`runtime.path`	Path of modules for the server to scan and load at startup. Default value is `data_dir/modules`.
`http_key`	`runtime.http_key`	A key used to authenticate HTTP Runtime invocations. Default value is `defaultkey`.

Important

You must change http_key before going live with your app!

Socket¶

Options related to connection socket and transport protocol between the server and clients.

Parameter	Flag	Description
`server_key`	`socket.server_key`	Server key to use to establish a connection to the server. Default value is `defaultkey`.
`port`	`socket.port`	The port for accepting connections from the client, listening on all interfaces. Default value is 7350.
`max_message_size_bytes`	`socket.max_message_size_bytes`	Maximum amount of data in bytes allowed to be read from the client socket per message. Default value is 1024.
`write_wait_ms`	`socket.write_wait_ms`	Time in milliseconds to wait for an ack from the client when writing data. Default value is 5000.
`pong_wait_ms`	`socket.pong_wait_ms`	Time in milliseconds to wait for a pong message from the client after sending a ping. Default value is 10000.
`ping_period_ms`	`socket.ping_period_ms`	Time in milliseconds to wait between client ping messages. This value must be less than the `pong_wait_ms`. Default value is 8000.

Important

You must change server_key before going live with your app!

Session¶

You can change configuration options related to each user session, such as the encryption key used to create the token.

Parameter	Flag	Description
`encryption_key`	`session.encryption_key`	The encryption key used to produce the client token. Default value is `defaultencryptionkey`.
`token_expiry_ms`	`session.token_expiry_ms`	Token expiry in milliseconds. Default value is 60000.

Important

You must change encryption_key before going live with your app!

Purchase¶

Nakama can verify in-app purchases by connecting to various stores and keeps a ledger of valid purchases. This is useful for preventing common in-app purchase replay attacks with valid receipts, as well as restoring purchases for user accounts as needed.

Apple¶

Apple In-App Purchase configuration

Parameter	Flag	Description
`password`	`apple.password`	Your application's shared secret.
`production`	`apple.production`	The order in which the reciept verification server will be contacted. Set `false` for test apps and `true` for live apps. Default is `false`.
`timeout_ms`	`apple.timeout_ms`	Connection timeout to connect to Apple services. Default value is 1500.

Google¶

Google In-App Purchase configuration

Parameter	Flag	Description
`package`	`google.package`	The package name the app is published under, such as `com.myapp.testapp`.
`service_key_file`	`google.service_key_file`	Absolute file path to the service key JSON file.
`timeout_ms`	`google..timeout_ms`	Connection timeout to connect to Google services. Default value is 1500.

Nakama can connect to various social networks to fetch user information. It can also act as a notification center for delivering and persisting notifications.

Notification¶

Parameter	Flag	Description
`expiry_ms`	`notification.expiry_ms`	Set notification expiry in milliseconds. Default value is 86400000 (1 day).

Steam¶

Configure Steam network settings. Facebook, Google and GameCenter don't require any server settings.

Parameter	Flag	Description
`publisher_key`	`steam.publisher_key`	Steam Publisher Key.
`app_id`	`steam.app_id`	Steam App ID.

Dashboard¶

This section defined the configuration related for the embedded Dashboard.

Parameter	Flag	Description
`port`	`dashboard.port`	The port for accepting connections to the dashboard, listening on all interfaces. Default value is 7351.

Cluster¶

This section configures how the nodes should connect to each to other form a cluster.

Nakama Enterprise Only

The following configuration options are available only in the Nakama Enterprise version of the Nakama server

Nakama is designed to run in production as a highly available cluster. You can start a cluster locally on your development machine if you’re running Nakama Enterprise. In production you can use either Nakama Enterprise or our Managed Cloud service.

Parameter	Flag	Description
`join`	`cluster.join`	List of hostname and port of other Nakama nodes to connect to.
`gossip_bindaddr`	`cluster.gossip_bindaddr`	Interface address to bind Nakama to for discovery. By default listening on all interfaces.
`gossip_bindport`	`cluster.gossip_bindport`	Port number to bind Nakama to for discovery. Default value is 7352.
`rpc_port`	`cluster.rpc_port`	Port number to use to send data between Nakama nodes. Default value is 7353.

Example File¶

You can use the entire file or just a subset of the configuration.

name: nakama-node-1
data_dir: "./data/"

log:
  stdout: false
  verbose: false

database:
  address:
    - "root@localhost:26257"
  conn_max_lifetime_ms: 60000
  max_open_conns: 0
  max_idle_conns: 0

runtime:
  env:
    - example_apikey: "example_apivalue"
  path: "/tmp/modules/folders"
  http_key: "defaultkey"

socket:
  server_key: "defaultkey"
  port: 7350
  max_message_size_bytes: 1024 # bytes
  write_wait_ms: 5000
  pong_wait_ms: 10000
  ping_period_ms: 8000 # Must be less than pong_wait_ms

session:
  encryption_key: "defaultencryptionkey"
  token_expiry_ms: 60000

purchase:
  apple:
    password: ""
    production: false
    expiry_ms: 1500
  google:
    package: ""
    service_key_file: ""
    expiry_ms: 1500

social:
  notification:
    expiry_ms: 86400000
  steam:
    publisher_key: ""
    app_id: 0

dashboard:
  port: 7351

cluster:
  join:
    - "10.0.0.2:7352"
    - "10.0.0.3:7352"
  gossip_bindaddr: "0.0.0.0"
  gossip_bindport: 7352
  rpc_port: 7353

Configuration¶

Specifying a config file¶

Common properties¶

Server Configuration¶

Log¶

Database¶

Runtime¶

Socket¶

Session¶

Purchase¶

Apple¶

Google¶

Social¶

Notification¶

Steam¶

Dashboard¶

Cluster¶

Example File¶