Compose: Getting started

  1. Clone the repository:

    git clone https://github.com/zulip/docker-zulip.git
cd docker-zulip

  2. Create your local configuration file from the example:

    cp compose.override.yaml.example compose.override.yaml

    compose.override.yaml is where deployment-specific configuration lives, and is not tracked in git so that pulling repository updates never conflicts with your local edits. The example file is the starting template; future upgrades may add new commented-out options to it that you can copy across.

  3. Configure the server settings; see Compose: Providing settings via environment.

  4. Configure Compose: Configuring TLS.

  5. Boot your Zulip installation for the first time, with:

    docker compose pull
docker compose run --rm zulip app:init

    This will boot all of Zulip’s dependencies, then verify the configuration and perform the initial database configuration. After a minute or two, the configuration should complete, ending with:

    === End Initial Configuration Phase ===

    If the output does not end with that, read the output carefully for warnings or errors.

  6. Now that we know configuration completed successfully, you can start Zulip:

    docker compose up zulip --wait

  7. Generate a link to create a new organization:

    ./manage.py generate_realm_creation_link

  8. Open that link in a browser to complete the organization creation steps and log in.

    If you elected to use a self-signed certificate, your browser will require that you click past a security warning.

    If you see other errors related to your TLS configuration, you may need to revisit Compose: Configuring TLS; after making any changes, re-run:

    docker compose up --wait

Next steps

See also