Self-host Zulip with Docker Compose

Organised team chat with topic-based threading for distributed teams.

zulip

memcached

memcached:alpine

postgres

zulip/zulip-postgresql:14

postgres-postgres-data-init

busybox

postgres-postgres-socket-init

busybox

rabbitmq

rabbitmq:4.0

redis

redis:5-alpine

redis-redis-data-init

busybox

This is still a work in progress.

The generated compose file and instructions may not be complete or correct for every app yet. Please report any issues you encounter to contact@bitflake.com.

The steps below take a few minutes end to end.

Docker compose setup and file
save the generated compose and env files.
Start Zulip with Docker Compose
bring the stack up and check it's healthy.

Requirements

You'll need these installed on the machine you're deploying to:

Docker

Packages Zulip and everything it depends on into an isolated container, so it runs the same way on your machine as it does everywhere else.

Install guide

Docker Compose

Reads docker-compose.ymland starts everything in it together. Ships with Docker Desktop. On Linux servers it's usually a separate install.

Install guide

1. Docker compose setup and file

Create a folder for Zulip and save the file below into it as docker-compose.yml. It describes every container the stack needs — Zulipitself and any supporting services, such as its database — along with the ports, volumes and environment variables each one uses. You'll also need an empty .env file in the same folder; Docker Compose reads it automatically and uses it to fill in the ${VARIABLE}references you'll see in the file below.

docker-compose.yml

version: "3.9"
services:
  memcached:
    image: memcached:alpine
    restart: unless-stopped
    network_mode: service:zulip
  postgres:
    image: zulip/zulip-postgresql:14
    restart: unless-stopped
    network_mode: service:zulip
    environment:
      POSTGRES_DB: zulip
      POSTGRES_PASSWORD: zulipdbpass
      POSTGRES_USER: zulip
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - postgres-socket:/var/run/postgresql
    depends_on:
      postgres-postgres-data-init:
        condition: service_completed_successfully
      postgres-postgres-socket-init:
        condition: service_completed_successfully
  postgres-postgres-data-init:
    image: busybox
    volumes:
      - postgres-data:/var/lib/postgresql/data
    command:
      - chown
      - 70:70
      - /var/lib/postgresql/data
  postgres-postgres-socket-init:
    image: busybox
    volumes:
      - postgres-socket:/var/run/postgresql
    command:
      - chown
      - 70:70
      - /var/run/postgresql
  rabbitmq:
    image: rabbitmq:4.0
    restart: unless-stopped
    network_mode: service:zulip
    environment:
      RABBITMQ_DEFAULT_PASS: zulippassword
      RABBITMQ_DEFAULT_USER: zulip
  redis:
    image: redis:5-alpine
    restart: unless-stopped
    network_mode: service:zulip
    volumes:
      - redis-data:/data
    depends_on:
      redis-redis-data-init:
        condition: service_completed_successfully
    command:
      - --requirepass
      - zulipredispass
  redis-redis-data-init:
    image: busybox
    volumes:
      - redis-data:/data
    command:
      - chown
      - 999:1000
      - /data
  zulip:
    image: ghcr.io/zulip/zulip-server:12.1-0
    restart: unless-stopped
    ports:
      - 80:80
    environment:
      LOADBALANCER_IPS: 10.244.0.0/16
      SECRETS_postgres_password: zulipdbpass
      SECRETS_rabbitmq_password: zulippassword
      SECRETS_redis_password: zulipredispass
      SETTING_EXTERNAL_HOST: zulip.localhost
      SETTING_MEMCACHED_LOCATION: localhost:11211
      SETTING_RABBITMQ_HOST: localhost
      SETTING_RABBITMQ_PASSWORD: zulippassword
      SETTING_REALM_HOSTS: '{"zulip": "zulip.localhost"}'
      SETTING_REDIS_HOST: localhost
      SETTING_REDIS_PASSWORD: zulipredispass
      SETTING_REMOTE_POSTGRES_HOST: localhost
      SETTING_REMOTE_POSTGRES_SSLMODE: disable
      SETTING_ZULIP_ADMINISTRATOR: admin@bitflake.com
      TRUST_GATEWAY_IP: "true"
    configs:
      - source: zulip-10-init.sh
        target: /data/post-setup.d/10-init.sh
        mode: 493
volumes:
  postgres-data: null
  postgres-socket: null
  redis-data: null
configs:
  zulip-10-init.sh:
    content: |
      #!/bin/bash
      set -e
      if su zulip -c "/home/zulip/deployments/current/manage.py shell \
        -c 'import sys; from zerver.models.realms import Realm; sys.exit(0 if Realm.objects.exists() else 1)'"; then
        echo "Realm already exists, skipping init."
        exit 0
      fi
      su zulip -c "/home/zulip/deployments/current/manage.py create_realm \
        --string-id=zulip --allow-reserved-subdomain --password='Admin123!' \
        'Zulip Demo' admin@bitflake.com 'Admin'"

2. Start Zulip with Docker Compose

From the folder with docker-compose.yml and .env, run:

Terminal

Start Zulip and all its supporting services in the background.

docker compose up -d

The -d flag runs the stack in the background so it keeps running after you close the terminal. Docker will pull the images the first time, which can take a minute or two.

To check on it afterwards: docker compose ps shows whether containers are healthy, and docker compose logs -f follows their logs if something looks wrong. Once it's running, open http://localhost:80 in your browser.