zulip/README.prod.md

This documents the process for installing Zulip in a production environment.

Recommended requirements:

• Server running Ubuntu Precise or Debian Wheezy
• At least 2 CPUs for production use
• At least 4GB of RAM for production use
• At least 100GB of free disk for production use
• HTTP(S) access to the public Internet (for some features; discuss with Zulip Support if this is an issue for you)
• SSL Certificate for the host you're putting this on (e.g. https://zulip.example.com)
• Email credentials for the service to send outgoing emails to users (e.g. missed message notifications, password reminders if you're not using SSO, etc.).

=======================================================================

How to install Zulip in production:

These instructions should be followed as root.

(1) Install the SSL certificates for your machine to /etc/ssl/private/zulip-enterprise.key and /etc/ssl/certs/zulip-enterprise.combined-chain.crt

(2) download zulip-server.tar.gz, and unpack to it /root/zulip, e.g. tar -xf zulip-server-1.1.3.tar.gz mv zulip-server-1.1.3 /root/zulip

(3) run /root/zulip/scripts/setup/install

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

(4) Configure the Zulip server instance by filling in the settings in /etc/zulip/settings.py

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

This will report an error if you did not fill in all the mandatory settings from /etc/zulip/settings.py. Once this completes successfully, the main installation process will be complete, and if you are planning on using password authentication, you should be able to visit the URL for your server and register for an account.

(6) Subscribe to https://groups.google.com/forum/#!forum/zulip-announce to get announcements about new releases, security issues, etc.

=======================================================================

Maintaining Zulip in production:

• To upgrade to a new version, download the appropriate release tarball from https://www.zulip.org, and then run as root

  /home/zulip/deployments/current/scripts/upgrade-zulip

  The upgrade process will shut down the service, run apt-get upgrade and any database migrations, and then bring the service back up. This will result in some brief downtime for the service, which should be under 30 seconds unless there is an expensive transition involved. Unless you have tested the upgrade in advance, we recommend doing upgrades at off hours.

  You can create your own release tarballs from a copy of this repository using tools/build-release-tarball.

• To update your settings, simply edit /etc/zulip/settings.py and then run /home/zulip/deployments/current/scripts/restart-server to restart the server

• You are responsible for running "apt-get upgrade" on your system on a regular basis to ensure that it is up to date with the latest security patches.

• To use the Zulip API with your Zulip server, you will need to use the API endpoint of e.g. "https://zulip.yourdomain.net/api". Our Python API example scripts support this via the "--site=https://zulip.yourdomain.net" argument. The API bindings support it via putting "site=https://zulip.yourdomain.net" in your .zuliprc.

• Similarly, you will need to instruct your users to specify the URL for your Zulip server when using the Zulip desktop and mobile apps.

• As a measure to mitigate the impact of potential memory leaks in one of the Zulip daemons, the service automatically restarts itself every Sunday early morning. See /etc/cron.d/restart-zulip for the precise configuration.

=======================================================================

SSO Authentication:

Zulip supports integrating with a corporate Single-Sign-On solution. There are a few ways to do it, but this section documents how to configure Zulip to use an SSO solution that best supports Apache and will set the REMOTE_USER variable:

(0) Check that /etc/zulip/settings.py has "zproject.backends.ZulipRemoteUserBackend" as the only enabled value in the "AUTHENTICATION_BACKENDS" list, and that "SSO_APPEND_DOMAIN" is correct set depending on whether your SSO system uses email addresses or just usernames in REMOTE_USER.

Make sure that you've restarted the Zulip server since making this configuration change.

(1) Edit /etc/zulip/zulip.conf and change the puppet_classes line to read:

puppet_classes = zulip::enterprise, zulip::apache_sso

(2) As root, run

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

to install our SSO integration.

(3) To configure our SSO integration, edit /etc/apache2/sites-available/zulip-sso.example and fill in the configuration required for your SSO service to set REMOTE_USER and place your completed configuration file at

/etc/apache2/sites-available/zulip-sso

(4) Run

a2ensite zulip-sso

To enable the Apache integration site.

Now you should be able to visit https://zulip.yourdomain.net/ and login via the SSO solution.