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 the --config flag.

1
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. See the documentation for configuring Nakama running on Docker.

Server ports #

Nakama is a very flexible system. You can exchange data with the server over gRPC, HTTP, Websockets and rUDP. Due to this flexibility, 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.

Common properties #

There are a few configuration properties that need to be changed in most environments, for example 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. The full list of configurations is at the bottom of the page.

ParameterDescription
nameNakama node name (must be unique) - It will default to nakama.
data_dirAn 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.pathPath of modules to scan and load. Defaults to data_dir/modules.
database.addressList 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_keyServer key to use to establish a connection to the server. Default value is defaultkey.
runtime.http_keyKey is used to protect the server’s runtime HTTP invocations. Default value is defaulthttpkey.
session.encryption_keyThe encryption key used to produce the client token. Default value is defaultencryptionkey.
session.token_expiry_secSession token expiry in seconds. Default value is 60.
session.refresh_encryption_keyThe encryption key used to produce the session refresh token. Default value is defaultrefreshencryptionkey.
session.refresh_token_expiry_secRefresh token expiry in seconds. Default value is 3600.

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:

1
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.

ParameterFlagDescription
namenameNakama node name (must be unique) - It will default to nakama. This name is also used in the log files.
data_dirdata_dirAn 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_secshutdown_grace_secMaximum 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 Heroic Cloud service.

ParameterFlagDescription
gossip_bindaddrcluster.gossip_bindaddrInterface address to bind Nakama to for discovery. By default listening on all interfaces.
gossip_bindportcluster.gossip_bindportPort number to bind Nakama to for discovery. Default value is 7352.
joincluster.joinList of hostname and port of other Nakama nodes to connect to.
max_message_size_bytescluster.max_message_size_bytesMaximum amount of data in bytes allowed to be sent between Nakama nodes per message. Default value is 4194304.
rpc_portcluster.rpc_portPort number to use to send data between Nakama nodes. Default value is 7353.
local_prioritycluster.local_priorityWhen set to true, prefer local resources where possible.
work_factor_interval_mscluster.work_factor_interval_msThe update frequency for work factor sync operations.

Console #

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

ParameterFlagDescription
addressconsole.addressThe IP address of the interface to listen for console traffic on. Default listen on all available addresses/interfaces.
max_message_size_bytesconsole.max_message_size_bytesMaximum amount of data in bytes allowed to be read from the client socket per message.
idle_timeout_msconsole.idle_timeout_msMaximum amount of time in milliseconds to wait for the next request when keep-alive is enabled.
passwordconsole.passwordPassword for the embedded console. Default is “password”.
portconsole.portThe port for accepting connections for the embedded console, listening on all interfaces. Default value is 7351.
read_timeout_msconsole.read_timeout_msMaximum duration in milliseconds for reading the entire request.
signing_keyconsole.signing_keyKey used to sign console session tokens.
token_expiry_secconsole.token_expiry_secToken expiry in seconds. Default 86400.
usernameconsole.usernameUsername for the embedded console. Default is “admin”.
write_timeout_msconsole.write_timeout_msMaximum 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.

ParameterFlagDescription
addressdatabase.addressList 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_msdatabase.conn_max_lifetime_msTime 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_connsdatabase.max_idle_connsMaximum number of allowed open but unused connections to the database. Default value is 100.
max_open_connsdatabase.max_open_connsMaximum number of allowed open connections to the database. Default value is 0 (no limit).
dns_scan_interval_secdatabase.dns_scan_interval_secNumber of seconds between scans looking for DNS resolution changes for the database hostname. Default 60.

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

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

IAP (In-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

ParameterFlagDescription
shared_passwordiap.apple.shared_passwordYour application’s shared password.
notifications_endpoint_idiap.apple.notifications_endpoint_idThe id of the endpoint to receive Apple Subscription Notifications. E.g.: Setting this to foo will activate the endpoint at path: /v2/console/apple/subscriptions/foo.

Google #

Google In-App Purchase configuration

ParameterFlagDescription
client_emailiap.google.client_emailThe Service Account Client Email value.
private_keyiap.google.private_keyThe Service Account Private Key value.
notifications_endpoint_idiap.google.notifications_endpoint_idThe id of the endpoint to receive Google Real-time developer notifications. E.g.: Setting this to foo will activate the endpoint at path: /v2/console/google/subscriptions/foo.
package_nameiap.google.notifications_endpoint_idThe package name of the app. Required if notifications_endpoint_id is set.
refund_check_period_miniap.google.refund_check_period_minThe periodicity of the background Google refund API checks. Required if a refund hook is set. Defaults to 15 minutes.

Huawei #

ParameterFlagDescription
public_keyhuawei.public_keyHuawei IAP store Base64 encoded Public Key.
client_idhuawei.client_idHuawei OAuth client secret.
client_secrethuawei.client_secretHuawei OAuth app client secret.

Leaderboard #

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

ParameterFlagDescription
blacklist_rank_cacheleaderboard.blacklist_rank_cacheDisable rank cache for leaderboards with matching leaderboard names. To disable rank cache entirely, use *, otherwise leave blank to enable rank cache.
callback_queue_sizeleaderboard.callback_queue_sizeSize of the leaderboard and tournament callback queue that sequences expiry/reset/end invocations. Default 65536.
callback_queue_workersleaderboard.callback_queue_workersNumber of workers to use for concurrent processing of leaderboard and tournament callbacks. Default 8.
rank_cache_workersleaderboard.rank_cache_workersThe number of parallel workers to use while populating leaderboard rank cache from the database. A higher number of workers usually makes the process faster but at the cost of increased database load. Default 1.

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).

ParameterFlagDescription
compresslogger.compressThis determines if the rotated log files should be compressed using gzip.
filelogger.fileLog output to a file (as well as stdout if set). Make sure that the directory and the file is writable.
formatlogger.formatSet logging output format. Can either be ‘JSON’ or ‘Stackdriver’. Default is ‘JSON’.
levellogger.levelMinimum log level to produce. Values are debug, info, warn and error. Default is info.
local_timelogger.local_timeThis 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_agelogger.max_ageThe 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_backupslogger.max_backupsThe 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_sizelogger.max_sizeThe maximum size in megabytes of the log file before it gets rotated. It defaults to 100 megabytes. Default is 100.
rotationlogger.rotationRotate log files. Default is false.
stdoutlogger.stdoutRedirect 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.

ParameterFlagDescription
call_queue_sizematch.call_queue_sizeSize of the authoritative match buffer that sequences calls to match handler callbacks to ensure no overlaps. Default 128.
deferred_queue_sizematch.deferred_queue_sizeSize of the authoritative match buffer that holds deferred message broadcasts until the end of each loop execution. Default 128.
input_queue_sizematch.input_queue_sizeSize of the authoritative match buffer that stores client messages until they can be processed by the next tick. Default 128.
join_attempt_queue_sizematch.join_attempt_queue_sizeSize of the authoritative match buffer that limits the number of in-progress join attempts. Default 128.
join_marker_deadline_msmatch.join_marker_deadline_msDeadline in milliseconds that client authoritative match joins will wait for match handlers to acknowledge joins. Default 5000.
label_update_interval_msmatch.label_update_interval_msTime in milliseconds between when match labels are updated. Default 1000.
max_empty_secmatch.max_empty_secMaximum 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 Prometheus.

ParameterFlagDescription
namespacemetrics.namespaceNamespace for Prometheus or prefix for Stackdriver metrics. It will always prepend node name. Default value is empty.
prefixmetrics.prefixPrefix for metric names. Default is ’nakama’, empty string ’’ disables the prefix.
prometheus_portmetrics.prometheus_portPort to expose Prometheus. Default value is ‘0’ which disables Prometheus exports.
reporting_freq_secmetrics.reporting_freq_secFrequency of metrics exports. Default is 60 seconds.

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

Runtime #

Options related to the runtime engine.

ParameterFlagDescription
call_stack_sizeruntime.call_stack_size(Deprecated) Size of each runtime instance’s call stack. Default 128.
envruntime.envList of Key-Value properties that are exposed to the Runtime scripts as environment variables.
event_queue_sizeruntime.event_queue_sizeSize of the event queue buffer. Default 65536.
event_queue_workersruntime.event_queue_workersNumber of workers to use for concurrent processing of events. Default 8.
http_keyruntime.http_keyA key used to authenticate HTTP Runtime invocations. Default value is defaultkey.
js_entrypointruntime.js_entrypointSpecifies the location of the bundled JavaScript runtime source code.
js_max_countruntime.js_max_countMaximum number of JavaScript runtime instances to allocate. Default 32.
js_min_countruntime.js_min_countMinimum number of JavaScript runtime instances to allocate. Default 16.
js_read_only_globalsruntime.js_read_only_globalsWhen enabled, marks all JavaScript runtime globals as read-only to reduce memory footprint. Default true.
lua_call_stack_sizeruntime.lua_call_stack_sizeSize of each runtime instance’s call stack. Default 128.
lua_max_countruntime.lua_max_countMaximum number of Lua runtime instances to allocate. Default 48.
lua_min_countruntime.lua_min_countMinimum number of Lua runtime instances to allocate. Default 16.
lua_read_only_globalsruntime.lua_read_only_globalsWhen enabled, marks all Lua runtime global tables as read-only to reduce memory footprint. Default true.
lua_api_stacktraceruntime.lua_api_stacktraceAdds the Lua stack trace in the API response. Default true.
lua_registry_sizeruntime.lua_registry_sizeSize of each Lua runtime instance’s registry. Default 512.
max_countruntime.max_count(Deprecated) Maximum number of runtime instances to allocate. Default 256.
min_countruntime.min_count(Deprecated) Minimum number of runtime instances to allocate. Default 16.
pathruntime.pathPath of modules for the server to scan and load at startup. Default value is data_dir/modules.
read_only_globalsruntime.read_only_globals(Deprecated) When enabled, marks all runtime global tables as read-only to reduce memory footprint. Default true.
registry_sizeruntime.registry_size(Deprecated) Size of each runtime instance’s registry. Default 512.

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

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

Satori #

Nakama can connect to Satori via the server runtime.

ParameterFlagDescription
urlsatori.urlThe URL of the Satori instance, in the format: https://<instance>.satoricloud.io:<port>.
api_key_namesatori.api_key_nameThe name of the Satori API key.
api_keysatori.api_keyThe Satori API key.
signing_keysatori.signing_keyThe key used to sign Satori session tokens.

Session #

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

ParameterFlagDescription
encryption_keysession.encryption_keyThe encryption key used to produce the client token. Default value is defaultencryptionkey.
token_expiry_secsession.token_expiry_secToken expiry in seconds. Default value is 60.
refresh_encryption_keysession.refresh_encryption_keyThe encryption key used to produce the session refresh token. Default value is defaultrefreshencryptionkey.
refresh_token_expiry_secsession.refresh_token_expiry_secRefresh token expiry in seconds. Default value is 3600.
single_socketsession.single_socketOnly allow one socket per user, older sessions are disconnected. Default false.
single_matchsession.single_matchOnly allow one match per user, older matches receive a leave. Requires single_socket to enable. Default false.
single_partysession.single_partyOnly allow one party per user. Older parties receive a leave. Requires single socket to enable. Default false.
single_sessionsession.single_sessionOnly allow one session token per user. Older session tokens are invalidated in the session cache. Default false.

Social #

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

Apple #

Configuration related to Apple iOS/iPadOS apps.

ParameterFlagDescription
bundle_idsocial.apple.bundle_idApple Sign In bundle ID.

Steam #

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

ParameterFlagDescription
app_idsocial.steam.app_idSteam App ID.
publisher_keysocial.steam.publisher_keySteam Publisher Key.

Facebook Instant Game #

Configuration relevant to Facebook Instant Games.

ParameterFlagDescription
app_secretsocial.facebook_instant_game.app_secretFacebook Instant App Secret.
app_idsocial.facebook_limited_login.app_idFacebook Limited Login App ID.

Socket #

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

The default values provided are optimized for a “responsive” feel in socket connections and should not be modified by inexperienced users. Contact Heroic Labs for assistance.
ParameterFlagDescription
addresssocket.addressThe IP address of the interface to listen for client traffic on. Default listen on all available addresses/interfaces.
idle_timeout_mssocket.idle_timeout_msMaximum amount of time in milliseconds to wait for the next request when keep-alive is enabled. Used for HTTP connections. Default value is 60000. Larger values are recommended only for local debugging, never in production.
max_message_size_bytessocket.max_message_size_bytesMaximum 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_bytessocket.max_request_size_bytesMaximum 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_sizesocket.outgoing_queue_sizeThe 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_thresholdsocket.ping_backoff_thresholdMinimum 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_mssocket.ping_period_msTime 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_mssocket.pong_wait_msTime in milliseconds to wait for a pong message from the client after sending a ping. Used for real-time connections. Default value is 25000.
portsocket.portThe port for accepting connections from the client, listening on all interfaces. Default value is 7350.
protocolsocket.protocolThe 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_buffer_size_bytessocket.read_buffer_size_bytesSize in bytes of the pre-allocated socket read buffer. Default 4096.
read_timeout_mssocket.read_timeout_msMaximum duration in milliseconds for reading the entire request. Used for HTTP connections. Default value is 10000.
server_keysocket.server_keyServer key to use to establish a connection to the server. Default value is defaultkey.
ssl_certificatesocket.ssl_certificatePath 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_keysocket.ssl_private_keyPath to private key file if you want the server to use SSL directly. Must also supply ssl_certificate. NOT recommended for production use.
response_headerssocket.response_headersAdditional headers to send to clients with every response. Values are only used if the response would not otherwise contain a value for the specified headers.
write_buffer_size_bytessocket.write_buffer_size_bytesSize in bytes of the pre-allocated socket write buffer. Default 4096.
write_timeout_mssocket.write_timeout_msMaximum duration in milliseconds before timing out writes of the response. Used for HTTP connections. Default value is 10000.
write_wait_mssocket.write_wait_msTime in milliseconds to wait for an ack from the client when writing data. Used for real-time connections. Default value is 5000. |

Tracker #

You can change configuration options related to session tracking.

ParameterFlagDescription
event_queue_sizetracker.event_queue_sizeSize 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 Heroic Cloud service.

ParameterFlagDescription
broadcast_period_mstracker.broadcast_period_msTime in milliseconds between tracker presence replication broadcasts to each cluster node. Default value is 1500.
clock_sample_periodstracker.clock_sample_periodsNumber 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_sizestracker.max_delta_sizesNumber of deltas and maximum presence count per delta for presence snapshots used to broadcast minimal subsets of presence data to cluster nodes. Used in periods of frequent presence changes to efficiently find the smallest set to sync between nodes. Note that the order of values matters. Default values are 100, 1000 and 10000.
max_silent_periodstracker.max_silent_periodsMaximum number of missed broadcasts before a cluster node’s presences are considered down. Default value is 10.
permdown_period_mstracker.permdown_period_msTime 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.

ParameterFlagDescription
max_ticketsmatchmaker.max_ticketsMaximum number of concurrent matchmaking tickets allowed per session or party. Default 3.
interval_secmatchmaker.interval_secHow quickly the matchmaker attempts to form matches, in seconds. Default 15.
max_intervalsmatchmaker.max_intervalsHow many intervals the matchmaker attempts to find matches at the max player count, before allowing min count. Default 2.
rev_precisionmatchmaker.rev_precisionReverse matching precision, i.e. if Player A matches with Player B the matchmaker will also check if Player B matches with Player A. Default false.
rev_thresholdmatchmaker.rev_thresholdThe number of matchmaker intervals to allow reverse matching before falling back to one-way matching. Default 1.

Google Auth #

You can change configuration options related to Google Auth.

ParameterFlagDescription
credentials_jsongoogle_auth.credentials_jsonThe content of the credentials file obtained on Google Console (The JSON file as a string).

Example file #

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
name: nakama-node-1
data_dir: "./data/"

logger:
  stdout: false
  level: "warn"
  file: "/tmp/path/to/logfile.log"
  rotation: false
  max_size: 100
  max_age: 0
  max_backups: 0
  local_time: false
  compress: false

metrics:
  reporting_freq_sec: 60
  namespace: ""
  prometheus_port: 7354

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
  local_priority: true
  work_factor_interval_ms: 1000

tracker:
  max_delta_sizes:
    - 100
    - 1000
    - 10000

matchmaker:
  max_tickets: 2
  interval_sec: 15
  max_intervals: 3

iap:
  apple:
    shared_password: "password"
  google:
    client_email: "email@google.com"
    private_key: "pk"
  huawei:
    public_key: "pk"
    client_id: "id"
    client_secret: "secret"