Install a Zulip server
Before you begin
To install a Zulip server, you’ll need an Ubuntu or Debian system that satisfies the installation requirements. Alternatively, you can use a preconfigured DigitalOcean droplet, or Zulip’s experimental Docker image.
Should I follow this installation guide?
If you would like to try out Zulip, you can start by checking it out in the Zulip development community, or create a test Zulip Cloud organization.
If you are deciding between self-hosting Zulip and signing up for Zulip Cloud, our self-hosting overview and guide to choosing between Zulip Cloud and self-hosting are great places to start.
If you’re developing for Zulip, you should follow the instructions to install Zulip’s development environment.
If you’d like to install a self-hosted Zulip server, this guide is for you!
Step 1: Download the latest release
Download and unpack the latest server release (Zulip Server 7.5) with the following commands:
cd $(mktemp -d) curl -fLO https://download.zulip.com/server/zulip-server-latest.tar.gz tar -xf zulip-server-latest.tar.gz
Step 2: Install Zulip
To set up Zulip with the most common configuration, you can run the installer as follows:
sudo -s # If not already root ./zulip-server-*/scripts/setup/install --certbot \ --email=YOUR_EMAIL --hostname=YOUR_HOSTNAME
This takes a few minutes to run, as it installs Zulip’s dependencies. For more on what the installer does, see details below.
If the script gives an error, consult Troubleshooting below.
--email@example.com: The email address for the person or team who maintains the Zulip installation. Note that this is a public-facing email address; it may appear on 404 pages, is used as the sender’s address for many automated emails, and is advertised as a support address. An email address like firstname.lastname@example.org is totally reasonable, as is email@example.com. Do not put a display name; e.g. “firstname.lastname@example.org”, not “Zulip Support email@example.com”. 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, and configures a cron job to renew the certificate automatically. If you’d prefer to acquire an SSL certificate yourself in any other way, it’s easy to provide it to Zulip.
You can see the more advanced installer options in our deployment options documentation.
Step 3: Create a Zulip organization, and log in
Otherwise, open the link in a browser. Follow the prompts to set up your organization, and your own user account as an administrator. Then, log in!
The link is a secure one-time-use link. If you need another
later, you can generate a new one by running
manage.py generate_realm_creation_link on the server. See also our
doc on running multiple organizations on the same
server if that’s what you’re planning to
Step 4: Configure and use
To really see Zulip in action, you’ll need to get the people you work together with using it with you.
Set up outgoing email so Zulip can confirm new users’ email addresses and send notifications.
Learn how to get your organization started using Zulip at its best.
Follow Zulip on Twitter.
Learn how to configure your Zulip server settings.
Details: What the installer does
The install script does several things:
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 PostgreSQL, RabbitMQ, Memcached and Redis.
Initializes Zulip’s database.
If you’d like to deploy Zulip with these services on different machines, check out our deployment options documentation.
Install script. 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.
zulip user’s password.
By default, the
zulip user doesn’t
have a password, and is intended to be accessed by
su zulip from the
root user (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 zulip turn out to
already have switched to the
zulip user earlier in their session,
and can just skip that step.
After the install script.
If you get an error after
scripts/setup/install completes, check
the bottom of
/var/log/zulip/errors.log for a traceback, and consult
the troubleshooting section for advice on
how to debug.
Still having trouble? Please see the troubleshooting and monitoring guide for additional advice and ways to get help.