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.

Shell

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.

Server ports¶

Nakama is a very flexible system. You can exchange data with the server over gRPC, HTTP, Websockets and rUDP. Due to this flexibilty, Nakama requires 4 ports to be available to bind to:

HTTP API server on port 7350. Port can be changed in the config.
HTTP API server powering the embedded developer console on port 7351. Port can be changed in the config.
gRPC API server on port 7349. Port is chosen based on the API server port.
gRPC API server for the embedded console on port 7348. Port is chosen based on the API server port.

We'll be reducing the port requirement in the future releases.

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`.
`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`.
`runtime.http_key`	Key is used to protect the server's runtime HTTP invocations. Default value is `defaulthttpkey`.
`session.encryption_key`	The encryption key used to produce the client token. Default value is `defaultencryptionkey`.
`session.token_expiry_sec`	Session token expiry in seconds. Default value is 60.
`session.refresh_encryption_key`	The encryption key used to produce the session refresh token. Default value is `defaultrefreshencryptionkey`.
`session.refresh_token_expiry_sec`	Refresh token expiry in seconds. Default value is 3600.

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.

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:

Shell

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`. 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.
`shutdown_grace_sec`	`shutdown_grace_sec`	Maximum number of seconds to wait for the server to complete work before shutting down. If 0 the server will shut down immediately when it receives a termination signal. Default value is `0`.

Cluster¶

This section configures how the nodes should connect to each other to 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
`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.
`join`	`cluster.join`	List of hostname and port of other Nakama nodes to connect to.
`max_message_size_bytes`	`cluster.max_message_size_bytes`	Maximum amount of data in bytes allowed to be sent between Nakama nodes per message. Default value is 4194304.
`rpc_port`	`cluster.rpc_port`	Port number to use to send data between Nakama nodes. Default value is 7353.

Console¶

This section defined the configuration related for the embedded developer console.

Parameter	Flag	Description
`address`	`console.address`	The IP address of the interface to listen for console traffic on. Default listen on all available addresses/interfaces.
`max_message_size_bytes`	`console.max_message_size_bytes`	Maximum amount of data in bytes allowed to be read from the client socket per message.
`idle_timeout_ms`	`console.idle_timeout_ms`	Maximum amount of time in milliseconds to wait for the next request when keep-alives are enabled.
`password`	`console.password`	Password for the embedded console. Default is "password".
`port`	`console.port`	The port for accepting connections for the embedded console, listening on all interfaces. Default value is 7351.
`read_timeout_ms`	`console.read_timeout_ms`	Maximum duration in milliseconds for reading the entire request.
`signing_key`	`console.signing_key`	Key used to sign console session tokens.
`token_expiry_sec`	`console.token_expiry_sec`	Token expiry in seconds. Default 86400.
`username`	`console.username`	Username for the embedded console. Default is "admin".
`write_timeout_ms`	`console.write_timeout_ms`	Maximum duration in milliseconds before timing out writes of the response.

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 0 (indefinite).
`max_idle_conns`	`database.max_idle_conns`	Maximum number of allowed open but unused connections to the database. Default value is 100.
`max_open_conns`	`database.max_open_conns`	Maximum number of allowed open 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"
```

Leaderboard¶

You can change configuration options related to the leaderboard and tournament systems.

Parameter	Flag	Description
`blacklist_rank_cache`	`leaderboard.blacklist_rank_cache`	Disable rank cache for leaderboards with matching leaderboard names.
`callback_queue_size`	`leaderboard.callback_queue_size`	Size of the leaderboard and tournament callback queue that sequences expiry/reset/end invocations. Default 65536.
`callback_queue_workers`	`leaderboard.callback_queue_workers`	Number of workers to use for concurrent processing of leaderboard and tournament callbacks. Default 8.

Disable rank cache

To disable rank cache entirely, use *, otherwise leave blank to enable rank cache.

Logger¶

Nakama produces logs in JSON format so various systems can interact with the logs. By default they are written to the standard out (console).

Parameter	Flag	Description
`compress`	`logger.compress`	This determines if the rotated log files should be compressed using gzip.
`file`	`logger.file`	Log output to a file (as well as `stdout` if set). Make sure that the directory and the file is writable.
`format`	`logger.format`	Set logging output format. Can either be 'JSON' or 'Stackdriver'. Default is 'JSON'.
`level`	`logger.level`	Minimum log level to produce. Values are `debug`, `info`, `warn` and `error`. Default is `info`.
`local_time`	`logger.local_time`	This determines if the time used for formatting the timestamps in backup files is the computer's local time. The default is to use UTC time.
`max_age`	`logger.max_age`	The maximum number of days to retain old log files based on the timestamp encoded in their filename. The default is not to remove old log files based on age.
`max_backups`	`logger.max_backups`	The maximum number of old log files to retain. The default is to retain all old log files (though `max_age` may still cause them to get deleted.)
`max_size`	`logger.max_size`	The maximum size in megabytes of the log file before it gets rotated. It defaults to 100 megabytes. Default is 100.
`rotation`	`logger.rotation`	Rotate log files. Default is false.
`stdout`	`logger.stdout`	Redirect logs to console standard output. The log file will no longer be used. Default is `true`.

The standard startup log messages will always be printed to the console irrespective of the value of logger.stdout field.

Match¶

You can change configuration options related to the authoritative multiplayer runtime.

Parameter	Flag	Description
`call_queue_size`	`match.call_queue_size`	Size of the authoritative match buffer that sequences calls to match handler callbacks to ensure no overlaps. Default 128.
`deferred_queue_size`	`match.deferred_queue_size`	Size of the authoritative match buffer that holds deferred message broadcasts until the end of each loop execution. Default 128.
`input_queue_size`	`match.input_queue_size`	Size of the authoritative match buffer that stores client messages until they can be processed by the next tick. Default 128.
`join_attempt_queue_size`	`match.join_attempt_queue_size`	Size of the authoritative match buffer that limits the number of in-progress join attempts. Default 128.
`join_marker_deadline_ms`	`match.join_marker_deadline_ms`	Deadline in milliseconds that client authoritative match joins will wait for match handlers to acknowledge joins. Default 5000.
`max_empty_sec`	`match.max_empty_sec`	Maximum number of consecutive seconds that authoritative matches are allowed to be empty before they are stopped. 0 indicates no maximum. Default 0.

Metrics¶

Nakama produces metrics information. This information can be exported to Stackdriver or Prometheus.

Parameter	Flag	Description
`namespace`	`metrics.namespace`	Namespace for Prometheus or prefix for Stackdriver metrics. It will always prepend node name. Default value is empty.
`prometheus_port`	`metrics.prometheus_port`	Port to expose Prometheus. Default value is '0' which disables Prometheus exports.
`reporting_freq_sec`	`metrics.reporting_freq_sec`	Frequency of metrics exports. Default is 60 seconds.
`stackdriver_projectid`	`metrics.stackdriver_projectid`	This is the identifier of the Stackdriver project the server is uploading the stats data to. Setting this enables metrics to be exported to Stackdriver.

Ensure that metrics exports are protected as they contain sensitive server information.

Runtime¶

Options related to Lua-based runtime engine.

Parameter	Flag	Description
`call_stack_size`	`runtime.call_stack_size`	Size of each runtime instance's call stack. Default 128.
`env`	`runtime.env`	List of Key-Value properties that are exposed to the Runtime scripts as environment variables.
`event_queue_size`	`runtime.event_queue_size`	Size of the event queue buffer. Default 65536.
`event_queue_workers`	`runtime.event_queue_workers`	Number of workers to use for concurrent processing of events. Default 8.
`http_key`	`runtime.http_key`	A key used to authenticate HTTP Runtime invocations. Default value is `defaultkey`.
`max_count`	`runtime.max_count`	Maximum number of runtime instances to allocate. Default 256.
`min_count`	`runtime.min_count`	Minimum number of runtime instances to allocate. Default 16.
`path`	`runtime.path`	Path of modules for the server to scan and load at startup. Default value is `data_dir/modules`.
`registry_size`	`runtime.registry_size`	Size of each runtime instance's registry. Default 512.

Important

You must change http_key before going live with your app!

Runtime env value

The runtime environment is a key-value pair. They are separated by the = character like this:

```
nakama --runtime.env "key=value" --runtime.env "key2=value2" --runtime.env "key3=valuecanhave=sign"
```

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_sec`	`session.token_expiry_sec`	Token expiry in seconds. Default value is 60.
`refresh_encryption_key`	`session.refresh_encryption_key`	The encryption key used to produce the session refresh token. Default value is `defaultrefreshencryptionkey`.
`refresh_token_expiry_sec`	`session.refresh_token_expiry_sec`	Refresh token expiry in seconds. Default value is 3600.

Important

You must change encryption_key before going live with your app!

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

Steam¶

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

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

Facebook Instant Game¶

Configuration relevant to Facebook Instant Games.

Parameter	Flag	Description
`app_secret`	`facebook_instant_game.app_secret`	Facebook Instant App Secret.

Socket¶

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

Parameter	Flag	Description
`address`	`socket.address`	The IP address of the interface to listen for client traffic on. Default listen on all available addresses/interfaces.
`idle_timeout_ms`	`socket.idle_timeout_ms`	Maximum amount of time in milliseconds to wait for the next request when keep-alives are enabled. Used for HTTP connections. Default value is 60000.
`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. Used for real-time connections. Default value is 4096.
`max_request_size_bytes`	`socket.max_request_size_bytes`	Maximum amount of data in bytes allowed to be read from clients per request. Used for gRPC and HTTP connections.. Default value is 4096.
`outgoing_queue_size`	`socket.outgoing_queue_size`	The maximum number of messages waiting to be sent to the client. If this is exceeded the client is considered too slow and will disconnect. Used when processing real-time connections. Default value is 16.
`ping_backoff_threshold`	`socket.ping_backoff_threshold`	Minimum number of messages received from the client during a single ping period that will delay the sending of a ping until the next ping period, to avoid sending unnecessary pings on regularly active connections. Default value is 20.
`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`. Used for real-time connections. Default value is 15000.
`pong_wait_ms`	`socket.pong_wait_ms`	Time in milliseconds to wait for a pong message from the client after sending a ping. Used for real-time connections. Default value is 25000.
`port`	`socket.port`	The port for accepting connections from the client, listening on all interfaces. Default value is 7350.
`protocol`	`socket.protocol`	The network protocol to listen for traffic on. Possible values are `tcp` for both IPv4 and IPv6, `tcp4` for IPv4 only, or `tcp6` for IPv6 only. Default `tcp`."
`read_timeout_ms`	`socket.read_timeout_ms`	Maximum duration in milliseconds for reading the entire request. Used for HTTP connections. Default value is 10000.
`server_key`	`socket.server_key`	Server key to use to establish a connection to the server. Default value is `defaultkey`.
`ssl_certificate`	`socket.ssl_certificate`	Path to certificate file if you want the server to use SSL directly. Must also supply ssl_private_key. NOT recommended for production use.
`ssl_private_key`	`socket.ssl_private_key`	Path to private key file if you want the server to use SSL directly. Must also supply ssl_certificate. NOT recommended for production use.
`write_timeout_ms`	`socket.write_timeout_ms`	Maximum duration in milliseconds before timing out writes of the response. Used for HTTP connections. Default value is 10000.
`write_wait_ms`	`socket.write_wait_ms`	Time in milliseconds to wait for an ack from the client when writing data. Used for real-time connections. Default value is 5000.

Important

You must change server_key before going live with your app!

Tracker¶

You can change configuration options related to session tracking.

Parameter	Flag	Description
`event_queue_size`	`tracker.event_queue_size`	Size of the tracker presence event buffer. Increase if the server is expected to generate a large number of presence events in a short time. Default value is 1024.

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
`broadcast_period_ms`	`tracker.broadcast_period_ms`	Time in milliseconds between tracker presence replication broadcasts to each cluster node. Default value is 1500.
`clock_sample_periods`	`tracker.clock_sample_periods`	Number of broadcasts before a presence transfer will be requested from a cluster node if one is not received as expected. Default value is 2.
`max_delta_sizes`	`tracker.max_delta_sizes`	Number of deltas and maximum presence count per delta for presence snapshots used to broadcast minimal subsets of presence data to cluster nodes. Default values are 100, 1000 and 10000.
`max_silent_periods`	`tracker.max_silent_periods`	Maximum number of missed broadcasts before a cluster node's presences are considered down. Default value is 10.
`permdown_period_ms`	`tracker.permdown_period_ms`	Time in milliseconds since last broadcast before a cluster node's presences are considered permanently down and will be removed. Default value is 1200000.

Matchmaker¶

You can change configuration options related to matchmaking.

Parameter	Flag	Description
`max_tickets`	`matchmaker.max_tickets`	Maximum number of concurrent matchmaking tickets allowed per session or party. Default 3.
`interval_sec`	`matchmaker.interval_sec`	How quickly the matchmaker attempts to form matches, in seconds. Default 15.
`max_intervals`	`matchmaker.max_intervals`	How many intervals the matchmaker attempts to find matches at the max player count, before allowing min count. Default 2.

Example File¶

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

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

logger:
    stdout: false
    level: "warn"
    file: "/tmp/path/to/logfile.log"

metrics:
    reporting_freq_sec: 60
    namespace: ""
    stackdriver_projectid: ""
    prometheus_port: 0

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

runtime:
    env:
    - "example_apikey=example_apivalue"
    - "encryptionkey=afefa==e332*u13=971mldq"
    path: "/tmp/modules/folders"
    http_key: "defaulthttpkey"

socket:
    server_key: "defaultkey"
    port: 7350
    max_message_size_bytes: 4096 # bytes
    read_timeout_ms: 10000
    write_timeout_ms: 10000
    idle_timeout_ms: 60000
    write_wait_ms: 5000
    pong_wait_ms: 10000
    ping_period_ms: 8000 # Must be less than pong_wait_ms
    outgoing_queue_size: 16

session:
    encryption_key: "defaultencryptionkey"
    token_expiry_sec: 60
    refresh_encryption_key: "defaultrefreshencryptionkey"
    refresh_token_expiry_sec: 3600

social:
    steam:
    publisher_key: ""
    app_id: 0

console:
    port: 7351
    username: "admin"
    password: "password"

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

matchmaker:
        max_tickets: 2
        interval_sec: 15
        max_intervals: 3

Configuration¶

Specifying a config file¶

Server ports¶

Common properties¶

Server Configuration¶

Cluster¶

Console¶

Database¶

Leaderboard¶

Logger¶

Match¶

Metrics¶

Runtime¶

Session¶

Social¶

Steam¶

Facebook Instant Game¶

Socket¶

Tracker¶

Matchmaker¶

Example File¶