Compose: Providing settings using files

With the Docker Compose deployment, the MANUAL_CONFIGURATION and LINK_SETTINGS_TO_DATA environment settings can be used to provide settings, and possibly secrets, manually. This takes the place of providing SETTING_ environment values.

Required settings

Note that the following settings are always required:

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

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

Manually control just the contents of settings.py

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.

Using compose.override.yaml to set MANUAL_CONFIGURATION and bind-mount the settings.py file into the container, will let you fully control Zulip’s system settings. It is easier to edit the contents this way, compared to LINK_SETTINGS_TO_DATA (below), but it has the tradeoff that the settings are not stored in the Docker volume alongside the secrets.

  1. Download the default template settings.py file, and save it on your Docker host system as settings.py.

  2. Edit it to set ZULIP_ADMINISTRATOR and EXTERNAL_HOST, at least. Zulip will not start unless those two values are updated.

  3. Edit other settings in the file; see the inline documentation in the file.

  4. Decide how to store and deploy your shared secrets; the example below uses the default configuration, of storing them in a .env file.

  5. Edit compose.override.yaml, and set MANUAL_CONFIGURATION: True, and add a bind volume which maps the edited settings.py file into the container.

    services:
  zulip:
    environment:
      MANUAL_CONFIGURATION: True
    volumes:
      ## Update the /path/to/your/settings.py to be where `settings.py` is on your Docker host.
      - /path/to/your/settings.py:/etc/zulip/settings.py

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

  6. Start the container deployment with docker compose up.

  7. If you make changes to your settings.py on your Docker host, or your secrets, you can update the deployment by re-running docker compose up.

Store settings.py in the Docker volume

Zulip’s Docker Compose deployment uses Docker volumes to persist configuration data; by default, this is just secrets and certificates, but can also include settings.

  1. Decide how to store and deploy your shared secrets; the example below uses the default configuration, of storing them in a .env file.

  2. Edit compose.override.yaml, and set MANUAL_CONFIGURATION: True and LINK_SETTINGS_TO_DATA: True:

    services:
  zulip:
    environment:
      MANUAL_CONFIGURATION: True
      LINK_SETTINGS_TO_DATA: True

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

  3. Bootstrap the volume with default settings; this command is expected to fail, since the default setting do not provide values for the required EXTERNAL_HOST or ZULIP_ADMINISTRATOR settings. However, it will provide the scaffolding in the volume which can be easily edited.

    docker compose run zulip app:init

  4. Edit the etc-zulip/setting.py file in the zulip volume, which will now have a template with potential configuration settings in it. There are a number of ways to edit a file in a Docker volume; the most straightforward is to run an editor in the container. The Zulip Docker container mounts the volume at /data, so this would look like:

    docker compose run --rm zulip sh -c \
  "apt-get update && apt-get install -y nano && nano /data/etc-zulip/settings.py"

    You will at very least need to provide values for EXTERNAL_HOST and ZULIP_ADMINISTRATOR; Zulip will not start unless those are updated. You may also wish to edit other settings in the file; see the inline documentation in the file.

    Save the file and exit the editor when you’re done making changes.

  5. Start the container deployment with docker compose up.

  6. Updates to secrets will be propagated into the volume every time the Zulip container starts. If you make changes to etc-zulip/zulip-secrets.conf in the volume, those changes will be overwritten by any secrets which the Zulip container receives; we suggest using the Docker compose file and environment to manage secrets.

  7. If you make changes to etc-zulip/settings.py in the volume, or your secrets, you can update the deployment by re-running docker compose up.

See also