Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Edit installation instructions for clarity. 

(cherry picked from commit 7f51161761)
This commit is contained in:
Alya Abbott 2024-02-14 20:52:44 -08:00 committed by Tim Abbott
parent 0fe967b1c2
commit de0688ff84
1 changed files with 80 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
docs/production/install.md
View File

@ -1,31 +1,43 @@
# Install a Zulip server # Install a Zulip server
## Before you begin You can choose from several convenient options for hosting Zulip:
To install a Zulip server, you'll need an Ubuntu or Debian system that satisfies - Follow these instructions to **install a self-hosted Zulip server on a system
[the installation requirements](requirements.md). Alternatively, of your choice**.
you can use a preconfigured - Use a preconfigured
[DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26), or [DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26)
Zulip's - Use Zulip's [experimental Docker image](deployment.md#zulip-in-docker).
[experimental Docker image](deployment.md#zulip-in-docker). - Use [Zulip Cloud](https://zulip.com/plans/) hosting. Read our [guide to choosing between Zulip Cloud and
self-hosting](https://zulip.com/help/getting-your-organization-started-with-zulip#choosing-between-zulip-cloud-and-self-hosting).
### Should I follow this installation guide? To **import data** from [Slack][slack-import], [Mattermost][mattermost-import], [Rocket.Chat][rocketchat-import], [Gitter][gitter-import], [Zulip Cloud][zulip-cloud-import], or [another Zulip
server][zulip-server-import], follow the linked instructions.
- If you would like to try out Zulip, you can start by [checking it out in the You can **try out Zulip** before setting up your own server by [checking
Zulip development community](https://zulip.com/try-zulip/), or [create a test it out](https://zulip.com/try-zulip/) in the Zulip development community, or
Zulip Cloud organization](https://zulip.com/new/). [creating a free test organization](https://zulip.com/new/) on Zulip Cloud.
- If you are deciding between self-hosting Zulip and signing up for [Zulip :::{note}
Cloud](https://zulip.com/plans/), our [self-hosting These instructions are for self-hosting Zulip. To
overview](https://zulip.com/self-hosting/) and [guide to choosing between [contribute](../contributing/contributing.md) to the project, set up the
Zulip Cloud and [development environment](../development/overview.md).
self-hosting](https://zulip.com/help/getting-your-organization-started-with-zulip#choosing-between-zulip-cloud-and-self-hosting) :::
are great places to start.
- If you're developing for Zulip, you should follow the instructions ## Installation process overview
to install Zulip's [development environment](../development/overview.md).
If you'd like to install a self-hosted Zulip server, this guide is for you! 0. [Set up a base server](#step-0-set-up-a-base-server)
1. [Download the latest release](#step-1-download-the-latest-release)
1. [Install Zulip](#step-2-install-zulip)
1. [Create a Zulip organization, and log in](#step-3-create-a-zulip-organization-and-log-in)
That's it! Once installation is complete, you can
[configure](settings.md) Zulip to suit your needs.
## Step 0: Set up a base server
Provision and log in to a fresh Ubuntu or Debian system in your preferred
hosting environment that satisfies the [installation
requirements](requirements.md) for your expected usage level.
## Step 1: Download the latest release ## Step 1: Download the latest release
@ -39,16 +51,13 @@ curl -fLO https://download.zulip.com/server/zulip-server-latest.tar.gz
tar -xf zulip-server-latest.tar.gz tar -xf zulip-server-latest.tar.gz
``` ```
- If you'd like to verify the download, we To verify the download, see [the sha256sums of our release
[publish the sha256sums of our release tarballs](https://download.zulip.com/server/SHA256SUMS.txt). tarballs](https://download.zulip.com/server/SHA256SUMS.txt).
- You can also
[install a pre-release version of Zulip](deployment.md#installing-zulip-from-git)
using code from our [repository on GitHub](https://github.com/zulip/zulip/).
## Step 2: Install Zulip ## Step 2: Install Zulip
To set up Zulip with the most common configuration, you can run the To set up Zulip with the most common configuration, run the installer as
installer as follows: follows:
```bash ```bash
sudo -s # If not already root sudo -s # If not already root
@ -57,67 +66,70 @@ sudo -s # If not already root
``` ```
This takes a few minutes to run, as it installs Zulip's dependencies. This takes a few minutes to run, as it installs Zulip's dependencies.
For more on what the installer does, [see details below](#details-what-the-installer-does). For more information, see [installer details](#details-what-the-installer-does)
and [troubleshooting](#troubleshooting) below.
If the script gives an error, consult [Troubleshooting](#troubleshooting) below.
#### Installer options #### Installer options
- `--email=you@example.com`: The email address for the person or team who - `--email=it-team@example.com`: The email address for the **person or team who
maintains the Zulip installation. Note that this is a public-facing email maintains the Zulip installation**. Zulip users on your server will see this
address; it may appear on 404 pages, is used as the sender's address for many as the contact email in automated emails, on help pages, on error pages, etc.
automated emails, and is advertised as a support address. An email address You can later configure a display name for your contact email with the
like support@example.com is totally reasonable, as is admin@example.com. Do `ZULIP_ADMINISTRATOR` [setting][doc-settings].
not put a display name; e.g. "support@example.com", not "Zulip Support
<support@example.com>". This becomes `ZULIP_ADMINISTRATOR`
([docs][doc-settings]) in the Zulip settings.
- `--hostname=zulip.example.com`: The user-accessible domain name for - `--hostname=zulip.example.com`: The user-accessible domain name for this Zulip
this Zulip server, i.e., what users will type in their web browser. server, i.e., what users will type in their web browser. This becomes
This becomes `EXTERNAL_HOST` ([docs][doc-settings]) in the Zulip `EXTERNAL_HOST` in the Zulip [settings][doc-settings].
settings.
- `--certbot`: With this option, the Zulip installer automatically obtains an
SSL certificate for the server [using Certbot][doc-certbot], and configures a
cron job to renew the certificate automatically. If you prefer to acquire an
SSL certificate another way, it's easy to [provide it to
Zulip][doc-ssl-manual].
- `--self-signed-cert`: With this option, the Zulip installer - `--self-signed-cert`: With this option, the Zulip installer
generates a self-signed SSL certificate for the server. This isn't generates a self-signed SSL certificate for the server. This isn't
suitable for production use, but may be convenient for testing. suitable for production use, but may be convenient for testing.
- `--certbot`: With this option, the Zulip installer automatically For advanced installer options, see our [deployment options][doc-deployment-options]
obtains an SSL certificate for the server [using
Certbot][doc-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][doc-ssl-manual].
You can see the more advanced installer options in our [deployment options][doc-deployment-options]
documentation. documentation.
:::{important}
If you are importing data, stop here and return to the import instructions for
[Slack][slack-import], [Mattermost][mattermost-import],
[Rocket.Chat][rocketchat-import], [Gitter][gitter-import], [Zulip
Cloud][zulip-cloud-import], [a server backup][zulip-backups], or [another Zulip
server][zulip-server-import].
:::
[doc-settings]: settings.md [doc-settings]: settings.md
[doc-certbot]: ssl-certificates.md#certbot-recommended [doc-certbot]: ssl-certificates.md#certbot-recommended
[doc-ssl-manual]: ssl-certificates.md#manual-install [doc-ssl-manual]: ssl-certificates.md#manual-install
[doc-deployment-options]: deployment.md#advanced-installer-options [doc-deployment-options]: deployment.md#advanced-installer-options
[zulip-backups]: export-and-import.md#backups
[slack-import]: https://zulip.com/help/import-from-slack
[mattermost-import]: https://zulip.com/help/import-from-mattermost
[rocketchat-import]: https://zulip.com/help/import-from-rocketchat
[gitter-import]: https://zulip.com/help/import-from-gitter
[zulip-cloud-import]: export-and-import.md#import-into-a-new-zulip-server
[zulip-server-import]: export-and-import.md#import-into-a-new-zulip-server
## Step 3: Create a Zulip organization, and log in ## Step 3: Create a Zulip organization, and log in
On success, the install script prints a link. If you're [restoring a When the installation process is complete, the install script prints a secure
backup][zulip-backups] or importing your data from [Slack][slack-import], one-time-use organization creation link. Open this link in your browser, and
or another Zulip server, you should stop here follow the prompts to set up your organization and your own user account. Your
and return to the import instructions. Zulip organization is ready to use!
[slack-import]: https://zulip.com/help/import-from-slack :::{note}
[zulip-backups]: export-and-import.md#backups You can generate a new organization creation link by running `manage.py
generate_realm_creation_link` on the server. See also our guide on running
[multiple organizations on the same server](multiple-organizations.md).
:::
Otherwise, open the link in a browser. Follow the prompts to set up ## Getting started with Zulip
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](multiple-organizations.md) if that's what you're planning to
do.
## Step 4: Configure and use
To really see Zulip in action, you'll need to get the people you work To really see Zulip in action, you'll need to get the people you work
together with using it with you. together with using it with you.