zulip/docs/ssl-certificates.md

Using Let's Encrypt

If you have a domain name and you've configured DNS to point to the server where you want to install Zulip, you can use Let's Encrypt to generate a valid, properly signed SSL certificates, for free.

Run all of these commands as root. If you're not already logged in as root, use sudo -i to start an interactive root shell.

First, install the Let's Encrypt client Certbot and then generate the certificate:

wget https://dl.eff.org/certbot-auto
chmod a+x certbot-auto
./certbot-auto certonly --standalone

Note: If you already had a webserver installed on this system (e.g. you previously installed Zulip and are now getting a cert), you will need to stop the webserver (e.g. service nginx stop) and start it again after (e.g. service nginx start) running the certbot command above.

Next, symlink the certificates to make them available where Zulip expects them. Be sure to replace YOUR_DOMAIN with your domain name.

ln -s /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem /etc/ssl/private/zulip.key
ln -s /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem /etc/ssl/certs/zulip.combined-chain.crt

Note: Certificates provided by Let's Encrypt are valid for 90 days and then need to be renewed. You can renew with this command:

./certbot-auto renew

Generating a self-signed certificate

If you aren't able to use Let's Encrypt, you can generate a self-signed ssl certificate. We recommend getting a real certificate using Let's Encrypt over this approach because browsers (and the the Zulip apps) will complain when connecting to your server that the certificate isn't signed (for good reason: self-signed certificates are a security risk!).

Run all the commands in this section as root. If you're not already logged in as root, use sudo -i to start an interactive root shell.

The quickest way to create a cert is to use the script we provide:

scripts/setup/generate-self-signed-certs zulip.example.com

from the root of your Zulip directory (replacing zulip.example.com with the hostname of your server i.e. whatever you're going to set as EXTERNAL_HOST).

Generating a self-signed cert manually

We also document the steps below if you want to create a cert manually, which will offer you an opportunity to set your organization name (etc.).

apt-get install openssl
openssl genrsa -des3 -passout pass:x -out server.pass.key 4096
openssl rsa -passin pass:x -in server.pass.key -out zulip.key
rm server.pass.key
openssl req -new -key zulip.key -out server.csr

# The last step above will ask some questions interactively.
# Run these after answering the questions about your cert.
openssl x509 -req -days 365 -in server.csr -signkey zulip.key -out zulip.combined-chain.crt
rm server.csr
cp zulip.key /etc/ssl/private/zulip.key
cp zulip.combined-chain.crt /etc/ssl/certs/zulip.combined-chain.crt

You will eventually want to get a properly signed SSL certificate, but this will let you finish the installation process.

If you are using a self-signed certificate with an IP address (no domain)

Finally, if you want to proceed with just an IP address, it is possible to finish a Zulip installation that way; just set EXTERNAL_HOST to be the IP address.