Compose: Providing settings via environment

The majority of server configuration is done through a file named settings.py. Zulip’s Docker deployment uses environment variables in the container, prefixed with SETTING_, to control the settings in this file.

Settings in zulip.conf are adjusted via environment variables prefixed with CONFIG_, and with the section and setting separated by __ – e.g., CONFIG_http_proxy__allow_addresses for customizing outgoing proxy rules. Running zulip-puppet-apply, as non-Docker instructions may tell you to do, is not explicitly necessary, as the Zulip Docker images does that on every startup.

Note that authentication methods are configured slightly differently than just settings.py settings.

Required settings

Note that the following settings are always required:

  • SETTING_EXTERNAL_HOST: The hostname your users will use to connect to your Zulip server. If you’re testing on your laptop, the default of localhost.localdomain is great.

  • SETTING_ZULIP_ADMINISTRATOR: The email address to receive error and support emails generated by the Zulip server and its users.

Providing settings in compose.override.yaml

The simplest way to add new environment variables to the Docker container is by editing a compose.override.yaml file.

By default, Docker Compose reads compose.yaml (such as the one checked into the repository) and then merges the configuration in compose.override.yaml on top of those settings. This lets the compose.yaml provided by this repository change as the Docker deployment gets upgraded, while the deployment-specific parts can be placed in compose.override.yaml.

  1. Read the default template settings.py file and find settings which you want to change.

  2. For every setting you want to configure, prepend SETTING_ to the name, and place it under the environment: attribute of the zulip service.

    Zulip’s Docker container will attempt to detect and warn about environment variables which are missing the SETTING_ prefix.

  3. Start the container deployment with docker compose up.

  4. If you make changes to your compose.override.yaml file, you can update the deployment by re-running docker compose up.

Example

In compose.override.yaml:

services:
  zulip:
    environment:
      ## The following two settings are _required_ to be set:
      SETTING_EXTERNAL_HOST: "zulip.example.com"
      SETTING_ZULIP_ADMINISTRATOR: "admin@example.com"

      ## More example settings:

      ## Turn off "new login" email notifications
      SETTING_SEND_LOGIN_EMAILS: False

      ## Set the Giphy API key
      SETTING_GIPHY_API_KEY: PS42beKkLnOUBOqb1BgTyna87ooKgthE

      ## Run workers multi-threaded, for less memory consumption
      CONFIG_application_server__queue_workers_multiprocess: false

You will also need to include a secrets section to configure Compose: Secrets management.

Providing settings in a zulip-settings.env file

Instead of providing container environment variables in compose.override.yaml, you can instead tell Docker Compose to read them from a dedicated environment file.

Note that this environment file is different from the one used to define secrets; that one is named .env and its environment is specifically for the Compose file itself, and is not passed down to the Zulip container.

  1. Read the default template settings.py file and find settings which you want to change.

  2. Create a zulip-settings.env file on your Docker host. In it, place settings that you want to configure, prepended with SETTING_.

    Be sure to read the details of the env_file format, particularly with respect to quoting.

  3. Edit compose.override.yaml, and point the zulip service to the environment file:

    services:
  zulip:
    env_file: /path/to/zulip-settings.env

  4. Start the container deployment with docker compose up.

  5. If you make changes to your zulip-settings.env or compose.override.yaml files, you can update the deployment by re-running docker compose up.

Example

In zulip-settings.env:

## The following two settings are _required_ to be set:
SETTING_EXTERNAL_HOST: zulip.example.com
SETTING_ZULIP_ADMINISTRATOR: admin@example.com

## More example settings:

## Turn off "new login" email notifications
SETTING_SEND_LOGIN_EMAILS: False

## Set the Giphy API key
SETTING_GIPHY_API_KEY: PS42beKkLnOUBOqb1BgTyna87ooKgthE

## Run workers multi-threaded, for less memory consumption
CONFIG_application_server__queue_workers_multiprocess: false

In compose.override.yaml:

services:
  zulip:
    env_file: /path/to/zulip-settings.env

You will also need to include a secrets section to configure Compose: Secrets management.

See also