Installing SSL Certificates¶
To keep your communications secure, Zulip runs over HTTPS only. You’ll need an SSL/TLS certificate.
Fortunately, since about 2017, new options can make getting and maintaining a genuine, trusted-by-browsers certificate no longer the chore (nor expense) that it used to be.
If you already have an SSL certificate, just install (or symlink) its files into place at the following paths:
/etc/ssl/private/zulip.keyfor the private key
/etc/ssl/certs/zulip.combined-chain.crtfor the certificate. Because Zulip uses nginx as its web server, this should be in the format of a chained certificate bundle.
Let’s Encrypt is a free, completely automated CA launched in 2016 to help make HTTPS routine for the entire Web. Zulip offers a simple automation for Certbot, a Let’s Encrypt client, to get SSL certificates from Let’s Encrypt and renew them automatically.
We recommend most Zulip servers use Certbot. You’ll want something else if:
- you have an existing workflow for managing SSL certificates that you prefer;
- you need wildcard certificates (support from Let’s Encrypt planned for early 2018); or
- your Zulip server is not on the public Internet. (In this case you can still use Certbot, but it’s less convenient; and you’ll want to ignore Zulip’s automation.)
At initial Zulip install¶
To enable the Certbot automation when first installing Zulip, just
--certbot flag when running the install script.
--certbot. You’ll need the hostname to be a real DNS name, and the
Zulip server machine to be reachable by that name from the public
After Zulip is already installed¶
To enable the Certbot automation on an already-installed Zulip server, run the following commands:
sudo -s # If not already root /home/zulip/deployments/current/scripts/setup/setup-certbot --hostname=HOSTNAME --email=EMAIL
where HOSTNAME is the domain name users see in their browser when
using the server (e.g.,
zulip.example.com), and EMAIL is a contact
address for the server admins.
How it works¶
When the Certbot automation in Zulip is first enabled, by either method, it creates an account for the server at the Let’s Encrypt CA; requests a certificate for the given hostname; proves to the CA that the server controls the website at that hostname; and is then given a certificate. (For details, refer to Let’s Encrypt.)
Then it records a flag in
/etc/zulip/zulip.conf saying Certbot is in
use and should be auto-renewed. A cron job checks that flag, then
checks if any certificates are due for renewal, and if they are (so
approximately once every 60 days), repeats the process of request,
prove, get a fresh certificate.
If you aren’t able to use Certbot, you can generate a self-signed SSL certificate. This isn’t suitable for production use (because it’s insecure, and because browsers and the Zulip apps will complain that it’s insecure), but may be convenient for testing.
To generate a self-signed certificate when first installing Zulip,
just pass the
--self-signed-cert flag when
running the install script.
To generate a self-signed certificate for an already-installed Zulip server, run the following commands:
sudo -s # If not already root /home/zulip/deployments/current/scripts/setup/generate-self-signed-cert HOSTNAME
where HOSTNAME is the domain name (or IP address) to use on the generated certificate.