# Compose: Providing settings via environment

The majority of {doc}`server configuration <zulip:production/settings>` 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.

{doc}`Settings <zulip:production/system-configuration>` 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 {doc}`outgoing proxy rules <zulip:production/deployment>`.
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 {doc}`authentication methods <compose-authentication>` are configured
slightly differently than just `settings.py` settings.

```{admonition} 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](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/)
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](zulip-repo:zproject/prod_settings_template.py) and find settings which
   you want to change.

1. For every setting you want to configure, prepend `SETTING_` to the name, and
   place it under [the `environment:` attribute](https://docs.docker.com/reference/compose-file/services/#environment) of the `zulip` service.

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

1. Start the container deployment with `docker compose up`.

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

```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
{doc}`compose-secrets`.

## 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](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#use-the-env_file-attribute).

Note that this environment file is different from the one used to define
{doc}`secrets <compose-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](zulip-repo:zproject/prod_settings_template.py) and find settings which
   you want to change.

1. 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](https://docs.docker.com/reference/compose-file/services/#env_file-format),
   particularly with respect to quoting.

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

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

1. Start the container deployment with `docker compose up`.

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

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

You will also need to include a `secrets` section to configure
{doc}`compose-secrets`.

## See also

- [Merging Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/)
- [Reference syntax for merging Compose files](https://docs.docker.com/reference/compose-file/merge/)
- [Using the `env_file` attribute in Compose files](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#use-the-env_file-attribute)
- [Reference syntax for `env_file` in Compose files](https://docs.docker.com/reference/compose-file/services/#env_file)
- {doc}`/reference/environment-vars`
- {doc}`compose-secrets`
- {doc}`compose-manual-configuration`