# Configuration **URL:** https://heroiclabs.com/docs/nakama/getting-started/configuration/ **Summary:** Overview of how to provide a custom configuration for your Nakama server, and all available configuration properties. **Keywords:** nakama config, nakama configuration, config, configuration, server configuration, configuration **Categories:** nakama, configuration, getting-started --- # Server configuration Use a YAML file to configure how your Nakama server runs: ports, database, runtime modules, console access, and more. This guide shows you how to supply a config file at startup, which options you’ll change first, and how to override values at run time. Running Nakama with Docker? See [Docker configuration](./docker-configuration/) to mount your config into the container so the server reads it at startup. ## Specifying a config file You can specify a configuration file at run time using the `--config` flag. ```sh nakama --config my-config.yml ``` ## 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](#server-configuration). {{< table name="nakama.getting-started.configuration.properties" >}} ## 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: ```sh 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](../../getting-started/commands/) page. {{< table name="nakama.getting-started.configuration.configuration" >}} ### Cluster This section configures how the nodes should connect to each other to form a cluster. {{< note "important" "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](https://heroiclabs.com/enterprise). In production you can use either Nakama Enterprise or our [Heroic Cloud](https://heroiclabs.com/heroic-cloud/) service. {{< / note >}} {{< table name="nakama.getting-started.configuration.cluster" >}} ### Console This section defined the configuration related for the embedded developer console. {{< table name="nakama.getting-started.configuration.console" >}} ### Database Nakama requires a CockroachDB server instance to be available. Nakama creates and manages its own database called `nakama` within the CockroachDB database. {{< table name="nakama.getting-started.configuration.database" >}} You can pass in multiple database addresses to Nakama via command like: ```sh 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 {{< table name="nakama.getting-started.configuration.iap-apple" >}} #### Google Google In-App Purchase configuration {{< table name="nakama.getting-started.configuration.iap-google" >}} #### Huawei {{< table name="nakama.getting-started.configuration.iap-huawei" >}} ### Leaderboard You can change configuration options related to the leaderboard and tournament systems. {{< table name="nakama.getting-started.configuration.leaderboard" >}} ### 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). {{< table name="nakama.getting-started.configuration.logger" >}} 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. {{< table name="nakama.getting-started.configuration.match" >}} ### Metrics Nakama produces metrics information. This information can be exported to Prometheus. {{< table name="nakama.getting-started.configuration.metrics" >}} Ensure that metrics exports are protected as they contain sensitive server information. ### Runtime Options related to the runtime engine. {{< table name="nakama.getting-started.configuration.runtime" >}} The runtime environment is a key-value pair. They are separated by the `=` character like this: ```sh nakama --runtime.env "key=value" --runtime.env "key2=value2" --runtime.env "key3=valuecanhave=sign" ``` ### Satori Nakama can connect to Satori via the server runtime. {{< table name="nakama.getting-started.configuration.satori" >}} ### Session You can change configuration options related to each user , such as the encryption key used to create the token. {{< table name="nakama.getting-started.configuration.session" >}} ### 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. {{< table name="nakama.getting-started.configuration.social-apple" >}} #### Steam Configure Steam network settings. Facebook, Google and GameCenter don't require any server settings. {{< table name="nakama.getting-started.configuration.social-steam" >}} #### Facebook Instant Game Configuration relevant to Facebook Instant Games. {{< table name="nakama.getting-started.configuration.social-facebook" >}} ### Socket Options related to connection socket and transport protocol between the server and clients. {{< note "important" >}} The default values provided are optimized for a "responsive" feel in socket connections and should not be modified by inexperienced users. [Contact Heroic Labs](mailto:support@heroiclabs.com) for assistance. {{< / note >}} {{< table name="nakama.getting-started.configuration.socket" >}} ### Tracker You can change configuration options related to session tracking. {{< table name="nakama.getting-started.configuration.tracker1" >}} {{< note "important" "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](https://heroiclabs.com/enterprise). In production you can use either Nakama Enterprise or our [Heroic Cloud](https://heroiclabs.com/heroic-cloud/) service. {{< / note >}} {{< table name="nakama.getting-started.configuration.tracker2" >}} ### Matchmaker You can change configuration options related to matchmaking. {{< table name="nakama.getting-started.configuration.matchmaker" >}} ### Google Auth You can change configuration options related to Google Auth. {{< table name="nakama.getting-started.configuration.google_auth" >}} ## Example file You can use the entire file or just a subset of the configuration. ```yaml 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" ```