Compose: Using existing services

It is possible to use only parts of Zulip’s Docker Compose configuration, and use already-existing services (e.g. an external database) for other parts of the deployment.

The external database must be accessible on the Docker network that contains the rest of the Zulip services.

  1. Create the zulip network:

    docker network create zulip

  2. Update your external service (e.g. PostgreSQL server) to be accessible via the zulip network. How to do this will vary based on your deployment.

  3. Default Zulip uses PostgreSQL’s built-in full-text search and needs no extensions, but search quality depends on the dictionary files the server has available for stemming. The zulip/zulip-postgresql image bundles a useful set; managed-database providers (e.g., Amazon RDS) often don’t ship those dictionaries and produce lower-quality results. To enable PGroonga for multi-language full-text search, the external server needs the pgroonga extension available.

  4. Create the user and database in the external service, if necessary.

  5. Update compose.override.yaml to update the list of service dependencies, remove the service you will manage externally, and use the zulip network:

    networks:
  zulip:
    external: true
services:
  # Removes the "database" service entirely
  database: !reset null

  redis:
    networks:
      - zulip
  memcached:
    networks:
      - zulip
  rabbitmq:
    networks:
      - zulip
  zulip:
    networks:
      - zulip
    depends_on:
      # "database" has been removed from this set
      - memcached
      - rabbitmq
      - redis
    environment:
      SETTING_REMOTE_POSTGRES_HOST: "external-database-hostname"

      # These are the default names, but you may need to change them
      # based on your database's configuration.
      CONFIG_postgresql__database_user: "zulip"
      CONFIG_postgresql__database_name: "zulip"

      # various settings as usual..

  6. Test that the container can connect to the database:

    docker compose run --rm app:managepy checks

  7. Start the containers:

    docker compose up

See also