zulip/docs/prod-install.md

Install in Production

Ensure you have an Ubuntu system that satisfies the installation requirements.

Prior to installing Zulip, you should have an Ubuntu 14.04 Trusty 64-bit server instance, with at least 4GB RAM, 2 CPUs, and 10 GB disk space. You should also have a domain name available and have updated its DNS record to point to the server.

Step 1: Install SSL Certificates

Zulip runs over https only and requires ssl certificates in order to work. It looks for the certificates in /etc/ssl/private/zulip.key and /etc/ssl/certs/zulip.combined-chain.crt. Note that Zulip uses nginx as its webserver and thus expects a chained certificate bundle

If you already have an SSL certificate, just install (or symlink) them into place at the above paths, and move on to the next step.

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 LetsEncrypt over this approach because your browser (and some of the Zulip clients) will complain when connecting to your server that the certificate isn't signed.

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.

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
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.

Step 2: Download and unpack latest release

Download the latest built server tarball and unpack it to /root/zulip.

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.

wget https://www.zulip.com/dist/releases/zulip-server-latest.tar.gz
mkdir -p /root/zulip && tar -xf zulip-server-latest.tar.gz --directory=/root/zulip --strip-components=1

Step 3: Run install script

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.

/root/zulip/scripts/setup/install

This may take a while to run, since it will install a large number of packages via apt.

The Zulip install script is designed to be idempotent, so if it fails, you can just rerun it after correcting the issue that caused it to fail. Also note that it automatically logs a transcript to /var/log/zulip/install.log; please include a copy of that file in any bug reports.

Step 4: Configure Zulip

Configure the Zulip server instance by editing /etc/zulip/settings.py and providing values for the mandatory settings, which are all found under the heading ### MANDATORY SETTINGS.

These settings include:

• EXTERNAL_HOST: the user-accessible Zulip domain name for your Zulip installation. This will be the domain for which you have DNS A records pointing to this server and for which you configured SSL certificates.

• ZULIP_ADMINISTRATOR: the email address of the person or team maintaining this installation and who will get support emails.

• ADMIN_DOMAIN: the domain for your organization. Usually this is the main domain used in your organization's email addresses.

• AUTHENTICATION_BACKENDS: a list of enabled authentication mechanisms. You'll need to enable at least one authentication mechanism by uncommenting its corresponding line, and then also do any additional configuration required for that backend as documented in the settings.py file. See the section on Authentication for more detail on the available authentication backends and how to configure them.

• EMAIL_*, DEFAULT_FROM_EMAIL, and NOREPLY_EMAIL_ADDRESS: Regardless of which authentication backends you enable, you must provide settings for an outgoing SMTP server so Zulip can send emails when needed. We highly recommend testing your configuration using manage.py send_test_email to confirm your outgoing email configuration is working correctly.

• ALLOWED_HOSTS: Replace * with the fully qualified DNS name for your Zulip server here.

Step 5: Run database initialization

To initialize the Zulip database for your production install, run:

su zulip -c /home/zulip/deployments/current/scripts/setup/initialize-database

Note the use of su zulip. The initialize-database command and others like it need to be run by the zulip user. You can do this by running each command with su zulip -c or by starting an interactive shell as the zulip user with sudo -u zulip -i.

The initialize-database script will report an error if you did not fill in all the mandatory settings from /etc/zulip/settings.py. It is safe to rerun it after correcting the problem if that happens.

Once this script completes successfully, the main installation process will be complete, and zulip services will be running.

Step 6: Subscribe

Subscribe to low-traffic the Zulip announcements Google Group to get announcements about new releases, security issues, etc.

Congratulations! Next: Logging in and creating users.