Skip to content
Klutch.sh Docs

Deploying a Zulip App

Introduction

Zulip is a powerful team chat platform with threaded conversations. This guide shows how to containerize Zulip with a Dockerfile, connect it to external PostgreSQL, Redis, and RabbitMQ services, persist data, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • Managed PostgreSQL, Redis, and RabbitMQ instances (or separate deployments).
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM zulip/zulip:latest


# Default Zulip port
ENV ZULIP_PORT=9991
EXPOSE 9991

Required environment variables

  • ZULIP_PORT=9991
  • SETTINGS_EXTERNAL_HOST – public host (e.g., example-app.klutch.sh)
  • SETTINGS_ZULIP_ADMINISTRATOR – admin email
  • DB_HOST, DB_USER, DB_PASS, DB_NAME – PostgreSQL connection
  • REDIS_HOST – Redis host
  • RABBITMQ_HOST, RABBITMQ_USER, RABBITMQ_PASSWORD
  • SECRETS_secret_key – strong secret key for Zulip

Optional environment variables

  • SETTINGS_ALLOWED_HOSTS – comma-separated hosts
  • SETTINGS_LOG_LEVEL=info
  • SETTINGS_EMAIL_HOST, SETTINGS_EMAIL_HOST_USER, SETTINGS_EMAIL_HOST_PASSWORD for SMTP
  • SETTINGS_MEMCACHED_HOST=127.0.0.1 if you run memcached separately

Persistence

Zulip stores uploads, avatars, and configs on disk:

  • Mount path: /data
  • Size: based on expected file uploads and retention

Networking

  • Protocol: HTTP
  • Internal port: 9991
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 9991 inside the container.
Terminal window
curl -I http://localhost:9991/health

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 9991.
  5. Add environment variables for the external services (PostgreSQL, Redis, RabbitMQ), SETTINGS_EXTERNAL_HOST, admin email, and SECRETS_secret_key. Mark secrets as sensitive.
  6. Attach a persistent volume at /data sized for uploads and configuration.
  7. Deploy. After the app starts, finish the Zulip setup via the web UI and create your organization and admin user.

Verification

  • UI: open https://example-app.klutch.sh and confirm the Zulip setup/login page loads.

  • Health:

    Terminal window
    curl -I https://example-app.klutch.sh/health

Next steps

  • Configure email for invitations and notifications.
  • Set up backups for PostgreSQL and the /data volume.
  • Tune Redis and RabbitMQ endpoints and credentials according to your throughput needs.