Configuring Kuzzle #

The Kuzzle configuration is stored in a kuzzlerc file found in the root folder of your Kuzzle installation.

Kuzzle uses rc to override its default configuration by either:

• loading parameters from a .kuzzlerc file (sample file) ;
• loading parameters from environment variables with a kuzzle_ prefix.

Use .kuzzlerc file #

You can write your custom config parameters in a .kuzzlerc and store it in $HOME/.kuzzlerc or one of these locations:

{
  "services": {
    "storageEngine": {
      "client": {
        "node": "http://localhost:9200"
      }
    }
  }
}

Use Environment Variables #

The name of the environment variable must match the path of the configuration parameter in the .kuzzlerc file. To set the name of the environment variable:

• Use the prefix kuzzle_,
• then append the parameter path (as defined in the .kuzzlerc file) by using a double underscore __ to separate each level of its hierarchy.

For example, the .kuzzlerc parameter services.storageEngine.client.node in example 1, is represented by the environment variable kuzzle_services__storageEngine__client__node:

export kuzzle_services__storageEngine__client__node="http://localhost:9200"

You can also pass stringified JSON values this way to override non-scalar values such as objects or arrays. To do so, prefix a valid stringified JSON with *json: to instruct Kuzzle to parse the content of the value as JSON.

Examples:

export kuzzle_security__restrictedProfileIds='*json:["default","foo","bar"]'
export kuzzle_services__common='*json:{"defaultInitTimeout":120000, "retryInterval":1000}'

Docker Compose #

Environment variables are particularly handy when running Kuzzle in a Docker container. Using Docker Compose, they can easily be configured in the environment section of the docker-compose.yml file. For example, here's how we pass environment variables to Kuzzle in our default docker-compose file:

services:
  kuzzle:
    image: kuzzleio/kuzzle:2
    cap_add:
      - SYS_PTRACE
    depends_on:
      - redis
      - elasticsearch
    environment:
      - kuzzle_services__storageEngine__client__node=http://elasticsearch:9200
      - kuzzle_services__internalCache__node__host=redis
      - kuzzle_services__memoryStorage__node__host=redis
      - kuzzle_security__authToken__secret=<a long random secret>
      - NODE_ENV=production

  redis:
    image: redis:8

  elasticsearch:
    image: kuzzleio/elasticsearch:7
    ulimits:
      nofile: 65536

Commonly used sections #

Application logs #

The server.appLogs section sets the log level (level, default info) and where the logs are sent (transport: stdout, a file, Loki or Elasticsearch). See the Internal Logger guide.

export kuzzle_server__appLogs__level=debug

Authentication tokens #

The security.authToken section configures the authentication tokens:

export kuzzle_security__authToken__secret="<a long random secret>"

Securing Redis #

Kuzzle uses Redis for its internal cache (services.internalCache) and for the memory storage (services.memoryStorage). By default it connects without credentials, which is only acceptable on a private network that nothing else can reach.

The options object of both sections is handed as-is to the ioredis client, so authentication and encryption need no Kuzzle-specific setting:

They work the same way with a single server, Sentinel or a Redis cluster. Set them on both sections, even when they point at the same server:

export kuzzle_services__internalCache__options__password="<redis password>"
export kuzzle_services__memoryStorage__options__password="<redis password>"

A password set through an environment variable is kept as text, even when it looks like a number (0123 stays 0123).

Secrets in API answers and dumps #

server:getConfig and admin:dump never return a secret: the value of any key named like one (password, passphrase, secret, token, apiKey, credentials, privateKey, key, pfx, auth...) is replaced with "***", the key itself is kept so that one can still tell whether it is set, and credentials in URLs (https://user:password@host) become https://user:***@host. This applies to plugin and application configuration too. The security section and http.routes are not returned at all. The dump masks the environment variables (nodejs.json) with the same rule.

Use Backend.config property #

The configuration of Kuzzle is also accessible through the Backend.config property.

It is possible to read or edit values of the configuration.

The set of keys that can be configured is available in the file .kuzzlerc.sample.jsonc

Example: Change configuration values

// Read a configuration value
console.log(`Kuzzle will listen on port ${app.config.content.server.port}`);

// Allow more concurrent requests
app.config.content.limits.concurrentRequests = 200;

// Listen to port 4242
app.config.content.server.port = 4242;