From 7f511617617bfda6e897113a05259637b02e3c26 Mon Sep 17 00:00:00 2001 From: Alya Abbott Date: Wed, 14 Feb 2024 20:52:44 -0800 Subject: [PATCH] docs: Edit installation instructions for clarity. --- docs/production/install.md | 148 ++++++++++++++++++++----------------- 1 file changed, 80 insertions(+), 68 deletions(-) diff --git a/docs/production/install.md b/docs/production/install.md index 5092a31cdd..6ebfb91da7 100644 --- a/docs/production/install.md +++ b/docs/production/install.md @@ -1,31 +1,43 @@ # 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 -[the installation requirements](requirements.md). Alternatively, -you can use a preconfigured -[DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26), or -Zulip's -[experimental Docker image](deployment.md#zulip-in-docker). +- Follow these instructions to **install a self-hosted Zulip server on a system + of your choice**. +- Use a preconfigured + [DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26) +- Use Zulip's [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 - Zulip development community](https://zulip.com/try-zulip/), or [create a test - Zulip Cloud organization](https://zulip.com/new/). +You can **try out Zulip** before setting up your own server by [checking +it out](https://zulip.com/try-zulip/) in the Zulip development community, or +[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 - Cloud](https://zulip.com/plans/), our [self-hosting - overview](https://zulip.com/self-hosting/) and [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) - are great places to start. +:::{note} +These instructions are for self-hosting Zulip. To +[contribute](../contributing/contributing.md) to the project, set up the +[development environment](../development/overview.md). +::: -- If you're developing for Zulip, you should follow the instructions - to install Zulip's [development environment](../development/overview.md). +## Installation process overview -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 @@ -39,16 +51,13 @@ curl -fLO https://download.zulip.com/server/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](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/). +To verify the download, see [the sha256sums of our release +tarballs](https://download.zulip.com/server/SHA256SUMS.txt). ## Step 2: Install Zulip -To set up Zulip with the most common configuration, you can run the -installer as follows: +To set up Zulip with the most common configuration, run the installer as +follows: ```bash 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. -For more on what the installer does, [see details below](#details-what-the-installer-does). - -If the script gives an error, consult [Troubleshooting](#troubleshooting) below. +For more information, see [installer details](#details-what-the-installer-does) +and [troubleshooting](#troubleshooting) below. #### Installer options -- `--email=you@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 support@example.com is totally reasonable, as is admin@example.com. Do - not put a display name; e.g. "support@example.com", not "Zulip Support - ". This becomes `ZULIP_ADMINISTRATOR` - ([docs][doc-settings]) in the Zulip settings. +- `--email=it-team@example.com`: The email address for the **person or team who + maintains the Zulip installation**. Zulip users on your server will see this + as the contact email in automated emails, on help pages, on error pages, etc. + You can later configure a display name for your contact email with the + `ZULIP_ADMINISTRATOR` [setting][doc-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][doc-settings]) 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` in the Zulip [settings][doc-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 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][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] +For advanced installer options, see our [deployment options][doc-deployment-options] 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-certbot]: ssl-certificates.md#certbot-recommended [doc-ssl-manual]: ssl-certificates.md#manual-install [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 -On success, the install script prints a link. If you're [restoring a -backup][zulip-backups] or importing your data from [Slack][slack-import], -or another Zulip server, you should stop here -and return to the import instructions. +When the installation process is complete, the install script prints a secure +one-time-use organization creation link. Open this link in your browser, and +follow the prompts to set up your organization and your own user account. Your +Zulip organization is ready to use! -[slack-import]: https://zulip.com/help/import-from-slack -[zulip-backups]: export-and-import.md#backups +:::{note} +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 -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 +## Getting started with Zulip To really see Zulip in action, you'll need to get the people you work together with using it with you.