# Compose: Providing settings using files

With the Docker Compose deployment, the {ref}`manual-configuration`
and {ref}`link-settings-to-data` environment settings can be used to provide
{doc}`settings <zulip:production/settings>`, and possibly secrets, manually.
This takes the place of [providing `SETTING_` environment values](compose-settings).

```{admonition} 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](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`.

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](zulip-repo-raw:zproject/prod_settings_template.py), and save it on your
   Docker host system as `settings.py`.

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

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

1. Decide [how to store and deploy your shared secrets](compose-secrets); the
   example below uses the default configuration, of storing them in a `.env`
   file.

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

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

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

1. 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](https://docs.docker.com/engine/storage/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](compose-secrets); the
   example below uses the default configuration, of storing them in a `.env`
   file.

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

   ```yaml
   services:
     zulip:
       environment:
         MANUAL_CONFIGURATION: True
         LINK_SETTINGS_TO_DATA: True
   ```

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

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

   ```bash
   docker compose run zulip app:init
   ```

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

   ```bash
   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.

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

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

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

- {doc}`compose-secrets`
- {doc}`compose-settings`