# Zulip + PostgreSQL + RabbitMQ + Redis

> Threaded group chat with topic organization.

- Category: Message Queues & Brokers
- Difficulty: advanced
- Components: zulip, postgresql, rabbitmq, redis, memcached
- Tags: zulip, chat, threading, topics, team-communication
- Source: https://docker.recipes/messaging/zulip-complete

## Overview

Zulip is an open-source team chat application that revolutionizes group communication through its unique topic-based threading system. Originally developed by a team of MIT graduates and later acquired by Dropbox before becoming open-source, Zulip combines the real-time nature of chat with the organized structure of email threads. Unlike traditional chat platforms where conversations flow chronologically, Zulip organizes messages into streams and topics, making it easy to follow multiple conversations simultaneously and catch up on missed discussions without losing context.

This deployment stack leverages PostgreSQL as Zulip's primary database for storing messages, user data, and organizational information, while RabbitMQ handles the message queuing system for real-time message delivery and background task processing. Redis provides session management and caching capabilities, significantly improving response times for frequently accessed data, while Memcached offers an additional caching layer for database query optimization. Together, these components create a robust messaging infrastructure capable of handling enterprise-scale communication loads.

This configuration is ideal for development teams, open-source projects, academic institutions, and organizations that value organized communication over chaotic chat streams. The combination provides enterprise-grade reliability with self-hosted control, making it perfect for teams requiring data sovereignty, custom integrations, or advanced administrative controls that aren't available in hosted chat solutions.

## Features

- Topic-based message threading that allows multiple conversations per stream without message interleaving
- PostgreSQL backend providing ACID compliance for message integrity and complex user permission queries
- RabbitMQ message queuing enabling real-time message delivery, push notifications, and background email processing
- Redis-powered session management and real-time presence indicators for online/offline status
- Memcached query result caching reducing PostgreSQL load for frequently accessed streams and user data
- Built-in LaTeX and syntax highlighting support for mathematical formulas and code discussions
- Advanced search capabilities leveraging PostgreSQL full-text search across messages, files, and user content
- Multi-protocol authentication support including LDAP, SAML, and social login integration

## Use cases

- Software development teams needing organized code review discussions and bug tracking conversations
- Academic research groups managing multiple concurrent project discussions with topic separation
- Open-source projects requiring public archives with searchable message history and contributor onboarding
- Remote-first organizations needing asynchronous communication that doesn't lose context across time zones
- Compliance-focused companies requiring self-hosted chat with full message retention and audit capabilities
- Educational institutions managing course discussions with topic-based assignment and lecture threads
- Technical support teams organizing customer issues by product area with persistent conversation history

## Prerequisites

- Minimum 4GB RAM available (2GB for PostgreSQL and Zulip, 1GB for RabbitMQ, 512MB for Redis/Memcached)
- Docker and Docker Compose v2.0+ installed with BuildKit support enabled
- Available ports 80, 443, and 5432 for web interface and database connections
- Valid email SMTP credentials for user registration and notification delivery
- SSL certificate or domain name for production deployment (self-signed certificates included for development)
- Basic understanding of message queuing concepts and PostgreSQL database administration

## docker-compose.yml

```yaml
services:
  zulip:
    image: zulip/docker-zulip:latest
    environment:
      - DB_HOST=postgres
      - DB_HOST_PORT=5432
      - DB_USER=zulip
      - SETTING_MEMCACHED_LOCATION=memcached:11211
      - SETTING_RABBITMQ_HOST=rabbitmq
      - SETTING_REDIS_HOST=redis
      - SECRETS_email_password=${EMAIL_PASSWORD}
      - SECRETS_rabbitmq_password=${RABBITMQ_PASSWORD}
      - SECRETS_postgres_password=${POSTGRES_PASSWORD}
      - SECRETS_secret_key=${SECRET_KEY}
      - SETTING_EXTERNAL_HOST=localhost
      - SETTING_ZULIP_ADMINISTRATOR=admin@example.com
      - SSL_CERTIFICATE_GENERATION=self-signed
    volumes:
      - zulip-data:/data
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - postgres
      - rabbitmq
      - redis
      - memcached
    networks:
      - zulip-network
    restart: unless-stopped

  postgres:
    image: zulip/zulip-postgresql:14
    environment:
      - POSTGRES_USER=zulip
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=zulip
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - zulip-network
    restart: unless-stopped

  rabbitmq:
    image: rabbitmq:3-management
    environment:
      - RABBITMQ_DEFAULT_USER=zulip
      - RABBITMQ_DEFAULT_PASS=${RABBITMQ_PASSWORD}
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    networks:
      - zulip-network
    restart: unless-stopped

  redis:
    image: redis:alpine
    volumes:
      - redis-data:/data
    networks:
      - zulip-network
    restart: unless-stopped

  memcached:
    image: memcached:alpine
    networks:
      - zulip-network
    restart: unless-stopped

volumes:
  zulip-data:
  postgres-data:
  rabbitmq-data:
  redis-data:

networks:
  zulip-network:
    driver: bridge
```

## .env

```bash
# Zulip
POSTGRES_PASSWORD=secure_postgres_password
RABBITMQ_PASSWORD=secure_rabbitmq_password
SECRET_KEY=your-very-long-secret-key-min-50-chars
EMAIL_PASSWORD=optional_email_password
```

## Usage notes

- Zulip at https://localhost
- Generate realm: manage.py generate_realm_creation_link
- Topic-based threading
- Mobile apps available
- LDAP/SAML auth supported

## Troubleshooting

- Zulip fails to start with database connection errors: Ensure PostgreSQL container is fully initialized before Zulip starts by checking postgres logs for 'database system is ready to accept connections'
- Messages not delivering in real-time: Verify RabbitMQ management interface at rabbitmq:15672 shows active queues and check RABBITMQ_PASSWORD matches between services
- Slow page load times and timeouts: Monitor Redis and Memcached connections using redis-cli ping and telnet memcached:11211 to verify caching layers are responsive
- User registration emails not sending: Validate SMTP settings in EMAIL_PASSWORD environment variable and check Zulip logs for email backend connection errors
- High memory usage and container restarts: Adjust PostgreSQL shared_buffers and work_mem settings, and monitor RabbitMQ queue depths for message backlog buildup
- SSL certificate warnings in browser: Replace self-signed certificates with proper domain certificates or configure SETTING_EXTERNAL_HOST to match your actual domain name

