Make sure you want to install a Zulip production server. If you’d instead like to test or develop a new feature, we recommend the Zulip server development environment instead.
You will need an Ubuntu system that satisfies the installation requirements. In short, you need:
- Either a dedicated machine, or a fresh VM on an existing machine.
- Ubuntu 16.04 Xenial or Ubuntu 14.04 Trusty, 64-bit. If you have a choice, install on Xenial, since Trusty is approaching its end-of-life and you’ll save yourself the work of upgrading a production installation.
- At least 2GB RAM and 10 GB disk space (4GB and 2 CPUs recommended for 100+ users).
- A DNS name, an SSL certificate, and credentials for sending email.
For most users, you can just use our handy
--certbotoption to generate the SSL certificate.
Step 1: Download the latest release¶
Download and unpack the latest built server tarball with the following commands:
cd $(mktemp -d) wget https://www.zulip.org/dist/releases/zulip-server-latest.tar.gz tar -xf zulip-server-latest.tar.gz
If you’d like to verify the download, we publish the sha256sums of our release tarballs.
Step 2: Install Zulip¶
You are reading a development version of the Zulip documentation. These instructions may not correspond to the latest Zulip Server release. See documentation for the latest release.
To set up Zulip with the most common configuration, you can run the installer as follows:
sudo -i # If not already root ./zulip-server-*/scripts/setup/install --certbot \ --email=YOUR_EMAIL --hostname=YOUR_HOSTNAME
This will take a while to run, since it will install a large number of dependencies from the PyPI and NPM repositories.
--email@example.com: The email address of the person or team who should get support and error emails from this Zulip server. This becomes
ZULIP_ADMINISTRATOR(docs) in the Zulip settings.
--hostname=zulip.example.com: The user-accessible domain name for this Zulip server, i.e., what users will type in their web browser. This becomes
EXTERNAL_HOST(docs) in the Zulip settings.
--self-signed-cert: With this option, the Zulip installer generates a self-signed SSL certificate for the server. This isn’t suitable for production use, but may be convenient for testing.
--certbot: With this option, the Zulip installer automatically obtains an SSL certificate for the server using Certbot. If you’d prefer to acquire an SSL certificate yourself in any other way, it’s easy to provide it to Zulip.
What the installer does¶
The install script does several things:
- Creates the
zulipuser, which the various Zulip servers will run as.
/home/zulip/deployments/, which the Zulip code for this deployment (and future deployments when you upgrade) goes into. At the very end of the install process, the script moves the Zulip code tree it’s running from (which you unpacked from a tarball above) to a directory there, and makes
/home/zulip/deployments/currentas a symbolic link to it.
- Installs Zulip’s various dependencies.
- Configures the various third-party services Zulip uses, including Postgres, RabbitMQ, Memcached and Redis.
Troubleshooting install failures¶
The Zulip install script is designed to be idempotent. This means that if it fails, then once you’ve corrected the cause of the failure, you can just rerun the script.
The install script automatically logs a transcript to
/var/log/zulip/install.log. In case of failure, you might find the
log handy for resolving the issue. Please include a copy of this log
file in any bug reports.
Step 3: Configure outgoing email¶
Configure the Zulip server instance by editing
/etc/zulip/settings.py to enable your server’s ability to send
EMAIL_HOST_USER: credentials for an outgoing email (aka “SMTP”) server that Zulip can use to send emails. See our guide for outgoing email for help configuring this.
Step 4: Test email configuration¶
Test your outgoing email configuration. This is important to test now, because email configuration errors are common, and your outgoing email configuration needs to be working in order for you to complete the installation.
Step 5: Initialize Zulip database¶
At this point, you are done doing things as root. The remaining
commands are run as the
zulip user. Change to the
and initialize the Zulip database for your production install:
su zulip # If you weren't already the zulip user /home/zulip/deployments/current/scripts/setup/initialize-database
initialize-database script will report an error if you did not
fill in all the mandatory settings from
is safe to rerun it after correcting the problem if that happens.
This completes the process of installing Zulip on your server. However, in order to use Zulip, you’ll need to create an organization in your Zulip installation.
Step 6: Create a Zulip organization and login¶
Run the organization (realm) creation management command :
su zulip # If you weren't already the zulip user /home/zulip/deployments/current/manage.py generate_realm_creation_link
This will print out a secure one-time-use link that allows creation of a new Zulip organization on your server.
Open the generated link with your web browser. You’ll see the “Create organization” page (screenshot here). Enter your email address and click Create organization.
Check your email to find the confirmation email and click the link. You’ll be prompted to finish setting up your organization and initial administrator user (screenshot here). Complete this form and log in!
Congratulations! You are logged in as an organization administrator for your new Zulip organization.
Step 7: Next steps¶
- Subscribe to the extremely low-traffic Zulip announcements email list to get important announcements for Zulip server administrators about new releases, security issues, etc.
- Follow Zulip on Twitter to get Zulip news.
- Learn how to setup your new Zulip organization.
- Learn how configure your Zulip server settings.
- Learn about maintaining a production Zulip server.
zulipuser’s password. By default, the
zulipuser doesn’t have a password, and is intended to be accessed by
su zulipfrom the
rootuser (or via SSH keys or a password, if you want to set those up, but that’s up to you as the system administrator). Most people who are prompted for a password when running
su zulipturn out to already have switched to the
zulipuser earlier in their session, and can just skip that step.
- If you get an error after
scripts/setup/installcompletes, check the bottom of
/var/log/zulip/errors.logfor a traceback, and consult the troubleshooting section for advice on how to debug.
- If that doesn’t help, please visit
in the Zulip development community server for
realtime help or email firstname.lastname@example.org with the full
traceback, and we’ll try to help you out! Please provide details like
the full traceback from the bottom of
/var/log/zulip/errors.login your report.