Introduction

Zulip is a fully open-source collaboration program and a great alternative to Slack. This guide will walk you through installation and basic configuration of Zulip so you can have fast, productive conversations with friends and coworkers. These instructions should be similar to the official docs, but I’ll provide additional information and context here to help you along the way. If these instructions seem daunting, consider using the marketplace app from DigitalOcean – it will handle Step 1 and the mandatory parts of 2 for you.

Step 0: Prepare your server

Step 1 is provisioning your server. Zulip is pretty light by default — I used the $12/mo High Frequency node closest to me in Chicago on Vultr, with Ubuntu 20.04, the latest stable version. You can use any VPS prodivder for this, but I wouldn’t reccomend hosting from a VM at home.

If you don’t already have Vultr, you can use this link to sign up and get a whopping $100 in starting credit. When you’re singed in, choose the right server size for you to continue. If you’re on Vultr or a similar provider, it’s easy to scale up, so there’s not a problem with starting small.

You likely don’t need IPv6, but I do recommend auto backups if you plan on using your Zulip install in a production environment. If you know how, using SSH keys is best. Once you’ve created your server, log in and let’s get started.

Step 1: Installation

We start by downloading and unpacking the latest release with these three commands. If you’re new to using the command line, try pasting them in one at a time rather than all at once.

My output looked this like this. You can see the directory change (note the part beofre the $ on line 2) and the download progress of the zip file. Unpacking (tar -xf) the file (this is very similar to unzipping a .zip, linux uses tar) does not return any result when it finsihes, but you can use ls to look.

You’ll need to now run sudo -s to elevate your permissions to the root user. This is similar to clicking “Allow” on popups in Windows or macOS when you install software. Now you’ll need to run another command, but it has two options, called flags, that you’ll want to edit. Copy and paste this template into notepad or something similar so we can edit it before entering it in your server:

Your email will become a Zulip administrator when the installation is finished. If you’re installing on behalf of a group or organization, use your organization account rather than your personal email, and consider using a shared account — this email will get support and error emails from the Zulip service.

The hostname is the URL of your server, like zulip.website.com. This hostname will need to be accessible from the internet for the HTTPS certificate to work properly. If you’re using Vultr, there’s two steps. First, get your IP address from the Vultr console. Then, log in to your DNS registrar (like Gandi, Cloudflare, or Namecheap) and create an A record for that IP address at your hostname. Computers don’t understand names by default, they only know where do go based on the IP address. The A record tells someone’s browser what IP address to find your server at when a human types the address.

Now that you’ve got your A record ready, let’s setup Zulip. Paste the command with your email and hostname into your Zulip server, and then wait a few minutes.

a quick note on HTTPS

You will then be asked to accept the terms and conditions for Let’s Encrypt, the HTTPS credential provider. HTTPS is how the communication from your Zulip app and the server stays secure.

If you get an error here, double check that your DNS is pointing to your server — you may need to wait a few minutes or even hours for it to go through. You can check to make sure your hostname is pointing at your ip with nslookup on windows or dig on macOS. Open your terminal and type nslookup YOUR_HOSTNAME and make sure that IP matches your Zulip machine.

• If you’re hosting at home, make sure your router or internet provider aren’t blocking ports 80 or 443.
• If you’re using a reverse proxy, make sure to follow Zulip’s instructions here

The installation will run for a few more minutes. When it’s done, you’ll get a realm creation link — copy and paste it into your browser to create your first administrator account!

Step 2: Initial configuration

After creating your account, you’ll see the main Zulip screen. You should also see a big red bar the top that alerts you that email isn’t working — let’s fix that.

Open your Zulip config file with nano /etc/zulip/settings.py. If you don’t have one already, create a Mailgun account and enter the information. Make sure you’re removing the # symbol preceding the configuration line.

Here’s an example:

Save your file, then add your password in zulip-secrets.conf as specified. That’s it, let’s test it out. Run su zulip -c ‘/home/zulip/deployments/current/manage.py send_test_email youremail@domain.com’ to send a test email. If it works, you’re good to continue. If not, check the troubleshooting steps here.

Mobile push notifications

We’re going to be editing /etc/zulip/settings.py a lot, so get comfy.

Open that file back up and uncomment the PUSH_NOTIFICATION_BOUNCER_URL line, then save and close the file. You should be logged in as the Zulip user already, and if you are, run /home/zulip/deployments/current/manage.py register_server. Otherwise, run su zulip -c ‘/home/zulip/deployments/current/manage.py register_server’ as root (this will run the registration command use the Zulip user). Then, just restart your server with /home/zulip/deployments/current/scripts/restart-server again.

If you had any users already logged into the mobile app, they need to log out and back in for push settings to apply.
This service relies on Kandra Labs to proxy your push messages. While some folks may not be comfortable with a third party seeing their push content, it’s a reasonable technical limitation. If you’re really committed, you can compile your own versions of the Zulip apps, which is a massive undertaking, and even after doing so Apple and Google can still see all of your push content. I don’t recommend doing this; it’s not worth the effort. Let’s do something fun instead — enable GIF searching!

Optional: GIPHY integration

This one’s easy and fun. Just uncomment the `GIPHY_API_KEY` line and enter your API key from the GIPHY developer console. You should choose SDK as the product type. Take your dev key and paste it in your settings.py file on the GIPHY line, then restart your server once more. When you’re back in, click the settings gear, click organization settings, then scroll down and enable GIPHY with your chosen age rating.

To get a production key, you’ll need to take a short video of you testing out your new (branded) GIPHY integration. When you’ve got it, just head back to your developer dashboard and hit the button to apply for a production key.

Step 3: Organization Settings

Now that your server is locked and loaded, what’s left? Well, you have a plain Zulip install — you probably want to set up moderators and posting policies. When you’re logged into Zulip, click the settings gear in the top right and then click Manage Organization. You should set an organization name, description, profile photo, and logos so people know who you are and what you’re all about.

• Under Organization settings, you way want to tweak the length of time a user can edit or delete a message. You can also choose to send weekly email digests to inactive users and a few other general things.
• Organization permissions is where you can decide who gets to add others to your Zulip server, what domains you will allow, weather new users have a waiting period before they are fully admitted, and more. These settings can help you prevent abuse by bots or swarms of trolls.
• Depending on how tightly you want to control your workspace, you can device who can create new streams. I recommend ensuring only admins or moderators can @all a stream.
• You may also want to restrict adding bots and custom emoji to admins only to help prevent abuse.
• Under Default Streams, you can decide what streams new users get added to automatically. This can be a great way to channel new users into a stream with volunteers that will give them personalized guidance on what to do next. Zulip can be overwhelming at first, like any chat app, and a human helping hand is always great.
• You can add custom fields to user’s profiles — this can be handy for properties specific to your organization.
• If your organization stores a lot of photos or media, take a look at using a file upload backend (this incurs additonal costs, but is much cheaper than buying a larger hard drive for your VM)

That’s the quick rundown of the important settings. Zulip has a lot more to offer that you can configure and modify to your heart’s content, but this should be enough to get you started. 

Good luck running your new Zulip install! Don’t forget to keep it update to date by patching it occasioanlly.