Zulip - Developer Guide

Learn how to install and configure Zulip on AWS with our step-by-step deployment guide. This resource walks you through provisioning your cloud environment, deploying Zulip securely, creating your first organization, and operating it reliably in a self-hosted AWS environment. Whether you're moving your team off a hosted chat subscription or want your conversations to stay inside your own AWS account, this guide will help you set up and run Zulip efficiently in the cloud.

Zulip takes a different approach from most team chat tools. Every message belongs to a channel and a topic, so conversations stay threaded and easy to catch up on. If you are still weighing your options, our Rocket.Chat vs Mattermost comparison and Mattermost vs Slack breakdown cover the other popular self-hosted choices. Let's get started deploying Zulip on AWS.

Launching the AMI

Step 1: Find and Select the Zulip AMI

1. Log in to your AWS Management Console.
2. Navigate to 'Zulip' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy Zulip" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail" used for SSL certificate generation.
3. Enter a value for "DeploymentName".
4. Provide a public domain for "DomainName". Zulip will automatically try to set up SSL if the domain is hosted on Route53. If unsuccessful, you must set up SSL manually.
5. Enter your SMTP server for "EmailHost" (for example, smtp.gmail.com).
6. Enter the SMTP password for "EmailHostPassword". For Gmail, use an app password rather than your account password.
7. Enter the SMTP username for "EmailHostUser", usually the full sending email address.
8. Enter the SMTP port for "EmailPort" (587 for STARTTLS).
9. Choose an instance type "InstanceType" (Recommended: t3a.small for small teams, larger as usage grows).
10. Select your preferred "KeyName".
11. Provide an S3 bucket name for "S3Bucket", used for storing backups.
12. Set "SSHLocation" to 0.0.0.0/0.
13. Keep "SubnetCidrBlock" as 10.0.0.0/24.
14. Keep "VpcCidrBlock" as 10.0.0.0/16.
15. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the details you've entered. Here's an example of a completed set of stack parameters:

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. Please wait for 5-10 minutes until the stack has been successfully created.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name and paste the copied PublicIp into the value textbox.
4. Click "Save".

Access Zulip

Access Zulip using the "DashboardUrl" or "DashboardUrlIp" provided in the Outputs tab.

A fresh Zulip server has no organization yet, so the first page you see is "No organization found". This is expected.

Clicking "New organization" will not help yet either. Zulip requires a secure, single-use link before anyone can create an organization on the server.

Step 1: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run the SSH command below.
3. Type "yes" and press Enter to confirm.

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Generate an organization creation link

Run Zulip's management command to generate the link:

sudo -u zulip /home/zulip/deployments/current/manage.py generate_realm_creation_link

Step 3: Create your organization

Open the link in your browser. Enter the Organization name, choose the Organization type and language, enter your email, and click "Create organization". Zulip sends a confirmation email to finish creating your admin account, which is why the SMTP parameters need to be correct.

The link works once. If you need another organization or the link expires, run the command again. If your team already uses a central identity provider, Zulip also supports SAML and OpenID Connect login - our Authentik developer guide shows how to run one on AWS.

Generate SSL Manually

Zulip will automatically try to set up SSL when a Route53-hosted domain is provided. If it fails, follow these steps to generate SSL manually.

Step 1: Copy IP Address

Follow the Update DNS steps above, if not already done, and copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 3: Generate SSL

Run Zulip's certbot setup script, replacing the admin email and domain with your own:

sudo /home/zulip/deployments/current/scripts/setup/setup-certbot --email=<admin-email> --agree-tos <your-domain>

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

Check that Zulip's services are running, then read the server and error logs:

sudo supervisorctl status

sudo tail -n 100 /var/log/zulip/server.log

sudo tail -n 100 /var/log/zulip/errors.log

Shutting Down Zulip

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the Zulip instance from the Instance state dropdown. You can restart it later as needed.

Remove Zulip

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete".

Upgrades

When a new version is available in AWS Marketplace, remove the previous deployment after backing up necessary server data, and relaunch with the new version.

Troubleshoot

1. If you face vCPU quota limits, request an increase: How to increase AWS quota.

2. If you face insufficient capacity errors while creating the stack, try another region or time.

3. If new users never receive their confirmation or invitation emails, check the EmailHost, EmailPort, EmailHostUser and EmailHostPassword values, then look for SMTP errors in /var/log/zulip/errors.log.

Check whether the instance storage is full - uploaded files and message history grow steadily on an active Zulip server.

• Log into the server and run:

df -h

• If the root volume is between 90-100%, resize the EBS volume (per AWS docs), then reboot and restart the service.

Conclusion

The Meetrix Zulip Deployment Guide helps you bring a self-hosted, topic-based team chat into your AWS environment. Whether you're a DevOps engineer, team lead, or IT administrator, this guide gives you step-by-step instructions for a secure and reliable setup. For other self-hosted tools on AWS, see our Rocket.Chat developer guide, our Zammad help desk guide, or the roundup of collaboration tools on AWS Marketplace.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with Zulip issues.

For questions about Zulip itself rather than the AWS deployment, the Zulip server documentation, the Zulip GitHub repository, and zulip.com are the best starting points.