Skip to main content

Install and Configure Zulip Chat

Zulip is an awesome open source, self hosted chat system made for teams and organizations. I was reached out to by the Zulip team to do a new, updated video on the project, and I'm so very glad they came to me. This project has gotten so incredibly good since I covered it way back when I was first starting my channel. I hope you'll enjoy it. I think it's an amazing option for all kinds of organizations. I really love the way it functions. It makes things so clean. 

My child is now in 9th grade. Each year her teachers tell her she needs to download some new app for their specific communication. These are usually some app with at least some level of free tier, and I hate this. They are all apps that want to send ads, and use my child's information for data gathering to sell for advertising, or some other form of profit. Understand, I do not blame these teachers. I blame the school district. This should not even be an option. The school district should be hosting their own communication platform, not using Slack, or Teams, or anything else hosted on other companies' servers, but they should be hosting their own. Setting it up for the teachers and students to login and have communication with their peers and teachers.  This shouldn't be something where I have to constantly worry about my child's information.  Zulip is just such a tool in my opinion.  I want to go and tell the school board my thoughts on this, but honestly, I just don't know what good it will do unless I determine the right way to convey that privacy is so very important. 

Setup a Server

Zulip recommends using a Debian 12 or Debian 13, or a Ubuntu 22..04 or 24.04 server for this installation. I'll be installing it in a container known as Incus. This is just a very tiny, efficient virtual machine. I'll be using Ubuntu 24.04 server for my container base OS. Feel free to use one you're comfortable with, but the commands should be the same.

In most self hosted applications these days, you'll need a machine to act as a server. This can be a machine in your home / business (such as an old laptop or desktop, a Raspberry PI or Single Board Computer (SBC), or even the computer you're reading this article from), a VM / Container hosted on one of your machines, or a VPS (Virtual Private Server) hosted by companies like RackNerd, Digital Ocean, Linode, Vultr, and so many more. Regardless of which option you choose, you'll want to do a few things to get the server setup properly.

Install updates to our Server

Ubuntu / Debian

sudo apt update && sudo apt upgrade -y

Add a non-root / sudo user on the server

Generally, when you setup a new server, the VPS (Virtual Private Server) service sets up a default "root" user for you. It's considered unsafe to do everything as "root", so let's setup a non-root user who has super user (sudo) privileges.

adduser <username> You'll be prompted to enter and confirm a password for this user. You'll also be asked for some user information like Name, etc, but this is not required information. At the end, confirm the entries, and you'll have your new user.

Next, we need to add the user to the super user group.

Ubuntu / Debian

usermod -aG sudo <username>

Now, you can log out of the system, and log back in as your new non-root super user.

Installing Zulip

  1. Make a Temp Directory for the Install

cd $(mktemp -d)

  1. Download the Install Archive

curl -fLO https://download.zulip.com/server/zulip-server-latest.tar.gz

  1. Unzip the Archive

tar -xf zulip-server-latest.tar.gz

  1. From the temp folder we made, become the super user (root) temporarily, and run the install script

sudo -s

If you want to run Zulip on a seerver that has it's own publicly accessible IPv4 Address use this command:

./zulip-server-*/scripts/setup/install --push-notifications --agree-to-terms-of-service --hostname=<chat.mygreatdomain.example> --email=<you@mygreatdomain.example> --certbot

If you don't want push notification, change --push-notifications to be --no-push-notifications.

The command below if for those wanting run behind a reverse proxy. as well as are the steps that follow it.

./zulip-server-*/scripts/setup/install --push-notifications --agree-to-terms-of-service --hostname=<chat.mygreatdomain.example> --email=you@mygreatdomain.example --self-signed-cert

This script does a lot! Be ready, it will take a while. On my system it took about 10 minutes or so to complete. Once it starts, it should not prompt you for anything if you use the command I have above.

Flags on the script are as follows:

  1. --push-nitofications - Enable push notifications for your site. This uses the Zulip hosted servers, so there are limitations depending on your organization, size, type, etc. (not a required flag)

  2. --agree-to-terms-of-service - Telling Zulip you agree to their terms of service for the push notification service (only required if you use the --push-notifications option as well.

  3. -hostname - The hostname you want to use for your site. For instance "chat.mycooldomain.com", or "zulip.awesomesauce.net". Only required if you want an FQDN (but highly recommended).

  4. --email - The email address of the person who will be the site administrator.

  5. --self-signed-cert - Allows you to get a self signed certificate for SSL. Zulip requires SSL connections for security reasons. This is only needed if you intend to use a Reverse Proxy to reach your zulip site, or you are using the IP of your server directly.

Additionally, the script creates a user called 'zulip', as well as a home directory for that user. There are command scripts stored here, so please do not delete this user or directory, or you will break your installation.

!!! IMPORTANT

When the installer completes successfully, you'll be provided a one time use link to be able to setup your initial organization and administrative user. You need to copy this link and keep it somewhere safe before continuing. We'll use this link once the site is up and we can reach it successfully.

Adjusting our Server Configuration for a Reverse Proxy

If you, like me, use a reverse proxy in order to get to your sites from the internet (if you don't, you should really consider it), then you'll need to do a bit of extra configuration setup. it's actually only about 3 lines of actual setup, but needs to be done. If you are not using a reverse proxy, then you can skip this section.

Adjust the .conf file to allow http_only connections so we can setup our reverse proxy:

nano /etc/zulip/zulip.conf

Change the contents by adding the following:

[application_server]
http_only = true

Use CTRL + O to save your changes, press Enter to confirm, and exit the nano editor with CTRL + X.

Apply our changes using the command script:

/home/zulip/deployments/current/scripts/zulip-puppet-apply

If prompted, answer 'y' for the application of changes.

Now we need to restart the Zulip server with the command script:

/home/zulip/deployments/current/scripts/restart-server

Next, depending on your proxy, you may need to setup header forwarding in the proxy itself.

Additionally, you'll need to add the IP(s) that your proxy will forward to the Zulip server in order to make sure Zulip can validate any connections.

This portion of the setup really threw me for a bit, but there are some logs you can use to help you figure out which IPs to show.

The two logs you can (should) check if needed are located at /var/log/zulip/errors.log and /var/log/zulip/server.log . Looking at these two logs after getting a few error pages when first attempting to reach my site, helped me resolve which IP addresses the Zulip seerver was getting from my reverse proxy.

I initially assumed that only the Pulbic IP address would be forwarded, but because I use Pangolin, it really has a 2 part setup. The server which has a public IPv4 address, and then a client running inside the network (called Newt), which acts as the entry point to the network for Pangolin. In my case, after looking through the logs, I found that Zulip was getting both the public IPv4 address of my Pangolin proxy server, as well as the private IPv4 address of the Newt node inside my network. To resolve the issues, I added both IPv4 addresses to the etc/zulip/zulip.conf file as follows:

nano /etc/zulip/zulip.conf

Add the following lines to your configuration file at the end. Make sure to replace my two placeholder IPv4 addresses with the actual IPv4 address(es) for your setup.

[loadbalancer]
# Use the IP addresses you determined above, separated by commas.
ips = 192.168.1.210,128.165.17.22

Where the first address is the Newt private IPv4 address, and the second is the Pangolin public IPv4 address.

Again, after adding this, I saved, my changes, applied them, and restarted the Zulip server.

Use CTRL + O to save your changes, press Enter to confirm, and exit the nano editor with CTRL + X.

Apply the changes with the command script:

/home/zulip/deployments/current/scripts/zulip-puppet-apply

Answer with 'y' if prompted about the changes. Next, restart the Zulip server with:

/home/zulip/deployments/current/scripts/restart-server

Try again to reach your site. If you can reach it successfully, then you should be able to use the special one-time use URL you copied earlier, and generate your first organization and administrative user.

Congratulations! You now have Zulip setup and running. You'll see an inbox, and a couple of walk throughs to help you understand how Zulip works. I highly recommend you check it out. It's really a robust, powerful system.

Special thanks go out to the Product Manager for Zulip, as she reached out and asked if I'd do an updated video on it, and I'm so glad she did. Additional thanks tot he Zulip community for helping me realize I should have been running some of the commands one line at a time, vs. in blocks like they appeared on the documentation, and for immediately updating the documentation to make this more clear to other users in the future!

No Comments
Back to top