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

155 lines
6.5 KiB
Markdown
Raw Normal View History

docs: Update README and installation guide. This is a general cleanup that also aims to link to the new self-hosting page to provide added context.
2022-02-12 01:32:47 +01:00
# Install a Zulip server
Move production install instructions to new page.
2016-07-12 21:49:44 +02:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
You can choose from several convenient options for hosting Zulip:
docs: Update README and installation guide. This is a general cleanup that also aims to link to the new self-hosting page to provide added context.
2022-02-12 01:32:47 +01:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
- 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).
docs: Make the intro to Production Installation less scary.
2019-07-20 00:50:50 +02:00
data_import: Remove gitter data import tool. Gitter broke their older API as part of being integrated into Matrix. Their announcement blog says: "Anything left using the Gitter APIs will need to be updated to use the Matrix API" This commit drops the legacy Gitter import tool and we plan to build a new one for Matrix in future.
2024-05-02 13:58:38 +02:00
To **import data** from [Slack][slack-import], [Mattermost][mattermost-import], [Rocket.Chat][rocketchat-import], [Zulip Cloud][zulip-cloud-import], or [another Zulip
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
server][zulip-server-import], follow the linked instructions.
docs: Update README and installation guide. This is a general cleanup that also aims to link to the new self-hosting page to provide added context.
2022-02-12 01:32:47 +01:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
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.
docs: Update README and installation guide. This is a general cleanup that also aims to link to the new self-hosting page to provide added context.
2022-02-12 01:32:47 +01:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
:::{note}
These instructions are for self-hosting Zulip. To
[contribute](../contributing/contributing.md) to the project, set up the
[development environment](../development/overview.md).
:::
docs: Update README and installation guide. This is a general cleanup that also aims to link to the new self-hosting page to provide added context.
2022-02-12 01:32:47 +01:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
## Installation process overview
docs: Clarify "Should I follow this installation guide?" instructions.
2023-03-30 16:22:14 +02:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
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.
docs: Expand production install docs. - Moves Let's Encrypt option for ssl certs above self-signed option. Updates Let's Excrypt instructions to user Certbot (new recommended method). Fixes #1426. - Adds and updates headings for clarity. - Adds new step 6 about configuring authentication (from prod-auth-first-login.html). - Adds emphasis on using `su zulip`, `sudo -u zulip -i`, and `sudo -i` where appropriate. Fixes #1356. Fixes #1245.
2016-07-28 01:38:02 +02:00
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
## Step 1: Download the latest release
docs: Expand production install docs. - Moves Let's Encrypt option for ssl certs above self-signed option. Updates Let's Excrypt instructions to user Certbot (new recommended method). Fixes #1426. - Adds and updates headings for clarity. - Adds new step 6 about configuring authentication (from prod-auth-first-login.html). - Adds emphasis on using `su zulip`, `sudo -u zulip -i`, and `sudo -i` where appropriate. Fixes #1356. Fixes #1245.
2016-07-28 01:38:02 +02:00
docs: Indicate latest Zulip version in installation and upgrade docs. With copy-editing from tabbott, and also a migration to use LATEST_RELEASE_VERSION, which will be correct even on the /latest/ paths. Fixes #19695.
2021-09-10 00:16:29 +02:00
Download and unpack [the latest server
release](https://download.zulip.com/server/zulip-server-latest.tar.gz)
(**Zulip Server {{ LATEST_RELEASE_VERSION }}**) with the following commands:
docs: Expand production install docs. - Moves Let's Encrypt option for ssl certs above self-signed option. Updates Let's Excrypt instructions to user Certbot (new recommended method). Fixes #1426. - Adds and updates headings for clarity. - Adds new step 6 about configuring authentication (from prod-auth-first-login.html). - Adds emphasis on using `su zulip`, `sudo -u zulip -i`, and `sudo -i` where appropriate. Fixes #1356. Fixes #1245.
2016-07-28 01:38:02 +02:00
docs: Add syntax highlighting languages to code blocks. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 07:09:04 +02:00
```bash
docs/prod*: Simplify core install instructions a bit by cutting /root/zulip . This works fine in my testing -- I followed it on a fresh `trusty` VM, after just getting SSL certs with our LetsEncrypt instructions, and the install completed successfully. And in the source tree, the only evidence I can find of a potential remaining dependency on the `/root/zulip` path is the Nagios config in `puppet/zulip_ops/`. That's actually already broken, in that it depends on `/root/zulip/api/`, so we'll have to sort that out; and in any case, it doesn't matter to most people installing Zulip. Add a mention that the install script will move the just-unpacked directory out from under you. While we're here, add a few words about where the deployed code is laid out. Text of those last words tweaked by tabbott.
2017-08-10 02:36:13 +02:00
cd $(mktemp -d)
tools: Switch to download.zulip.com from www.zulip.org.
2021-08-26 04:14:59 +02:00
curl -fLO https://download.zulip.com/server/zulip-server-latest.tar.gz
docs/prod*: Simplify core install instructions a bit by cutting /root/zulip . This works fine in my testing -- I followed it on a fresh `trusty` VM, after just getting SSL certs with our LetsEncrypt instructions, and the install completed successfully. And in the source tree, the only evidence I can find of a potential remaining dependency on the `/root/zulip` path is the Nagios config in `puppet/zulip_ops/`. That's actually already broken, in that it depends on `/root/zulip/api/`, so we'll have to sort that out; and in any case, it doesn't matter to most people installing Zulip. Add a mention that the install script will move the just-unpacked directory out from under you. While we're here, add a few words about where the deployed code is laid out. Text of those last words tweaked by tabbott.
2017-08-10 02:36:13 +02:00
tar -xf zulip-server-latest.tar.gz
docs: Expand production install docs. - Moves Let's Encrypt option for ssl certs above self-signed option. Updates Let's Excrypt instructions to user Certbot (new recommended method). Fixes #1426. - Adds and updates headings for clarity. - Adds new step 6 about configuring authentication (from prod-auth-first-login.html). - Adds emphasis on using `su zulip`, `sudo -u zulip -i`, and `sudo -i` where appropriate. Fixes #1356. Fixes #1245.
2016-07-28 01:38:02 +02:00
```
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
To verify the download, see [the sha256sums of our release
tarballs](https://download.zulip.com/server/SHA256SUMS.txt).
Add sha256sum integrity check to the release tarball. This stems from the discussion at https://chat.zulip.org/#narrow/stream/general/topic/signing.20the.20release
2017-10-17 09:29:40 +02:00
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
## Step 2: Install Zulip
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
To set up Zulip with the most common configuration, run the installer as
follows:
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
docs: Add syntax highlighting languages to code blocks. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 07:09:04 +02:00
```bash
docs: Use `sudo -s` to get a root shell without changing directory. The `-i` is for "initial", creating a login shell -- which means cd'ing to root's homedir. That defeats the line after this one.
2018-09-25 21:22:02 +02:00
sudo -s # If not already root
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
./zulip-server-*/scripts/setup/install --certbot \
docs: Revise description of main install step. Bulleted information instead of prose, huzzah! Also I think we need to explain the options a bit right here, or at least link to where they're documented somewhere. (If the list gets much longer, we'll want to shift toward the latter.) Also reorganize existing information a bit, and clean up a couple of nits.
2017-12-13 04:54:10 +01:00
--email=YOUR_EMAIL --hostname=YOUR_HOSTNAME
docs: Expand production install docs. - Moves Let's Encrypt option for ssl certs above self-signed option. Updates Let's Excrypt instructions to user Certbot (new recommended method). Fixes #1426. - Adds and updates headings for clarity. - Adds new step 6 about configuring authentication (from prod-auth-first-login.html). - Adds emphasis on using `su zulip`, `sudo -u zulip -i`, and `sudo -i` where appropriate. Fixes #1356. Fixes #1245.
2016-07-28 01:38:02 +02:00
```
docs: Move installation troubleshooting section to troubleshooting.md.
2024-02-15 21:35:03 +01:00
This takes a few minutes to run, as it installs Zulip's dependencies. It is
designed to be idempotent: if the script fails, once you've corrected the cause
of the failure, you can just rerun the script. For more information, see
[installer details](deployment.md#zulip-installer-details) and
[troubleshooting](troubleshooting.md#troubleshooting-the-zulip-installer).
install docs: Consolidate troubleshooting at bottom. This helps shorten the wall of text between the start of the instructions and the end. Conversely, now that there are fewer followup steps, the troubleshooting section at the end isn't so far away to point.
2018-03-03 01:49:08 +01:00
docs: Revise description of main install step. Bulleted information instead of prose, huzzah! Also I think we need to explain the options a bit right here, or at least link to where they're documented somewhere. (If the list gets much longer, we'll want to shift toward the latter.) Also reorganize existing information a bit, and clean up a couple of nits.
2017-12-13 04:54:10 +01:00
#### Installer options
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
- `--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].
docs: Revise description of main install step. Bulleted information instead of prose, huzzah! Also I think we need to explain the options a bit right here, or at least link to where they're documented somewhere. (If the list gets much longer, we'll want to shift toward the latter.) Also reorganize existing information a bit, and clean up a couple of nits.
2017-12-13 04:54:10 +01:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
- `--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].
docs: Revise description of main install step. Bulleted information instead of prose, huzzah! Also I think we need to explain the options a bit right here, or at least link to where they're documented somewhere. (If the list gets much longer, we'll want to shift toward the latter.) Also reorganize existing information a bit, and clean up a couple of nits.
2017-12-13 04:54:10 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- `--self-signed-cert`: With this option, the Zulip installer
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
generates a self-signed SSL certificate for the server. This isn't
install docs: Document streamlined self-signed-cert flow. This is easy now, so make it known to admins who are looking for a fast path for a test install. Also totally cut the painfully complicated steps for generating a self-signed cert by hand. Anyone who actually wants that can find a hundred explanations on the Web, or can look at our script if they want to specifically mirror how we do it (which is mercifully much simpler than this.)
2018-01-24 02:54:23 +01:00
suitable for production use, but may be convenient for testing.
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
For advanced installer options, see our [deployment options][doc-deployment-options]
docs: Update install docs to document the install options correctly. Update `docs/production/install.md` and `docs/production/deployment.md` to document the install flags that can be used as part of the installer more clearly. Fixes #18122.
2021-04-18 04:01:20 +02:00
documentation.
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
:::{important}
If you are importing data, stop here and return to the import instructions for
[Slack][slack-import], [Mattermost][mattermost-import],
data_import: Remove gitter data import tool. Gitter broke their older API as part of being integrated into Matrix. Their announcement blog says: "Anything left using the Gitter APIs will need to be updated to use the Matrix API" This commit drops the legacy Gitter import tool and we plan to build a new one for Matrix in future.
2024-05-02 13:58:38 +02:00
[Rocket.Chat][rocketchat-import], [Zulip Cloud][zulip-cloud-import], [a server backup][zulip-backups], or [another Zulip server][zulip-server-import].
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
:::
docs: Clean redundant relative links. We previously had a convention of redundantly including the directory in relative links to reduce mistakes when moving content from one file to another. However, these days we have a broken link checker in test-documentation, and after #21237, MyST-Parser will check relative links (including fragments) when you run build-docs. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-24 00:17:21 +01:00
[doc-settings]: settings.md
docs: Convert .html#fragment links to .md#fragment. This uses the myst_heading_anchors option to automatically generate header anchors and make Sphinx aware of them. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors. Note: to be compatible with GitHub, MyST-Parser uses a slightly different convention for .md fragment links than .html fragment links when punctuation is involved. This does not affect the generated fragment links in the HTML output. Fixes #13264. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-16 01:39:15 +01:00
[doc-certbot]: ssl-certificates.md#certbot-recommended
[doc-ssl-manual]: ssl-certificates.md#manual-install
[doc-deployment-options]: deployment.md#advanced-installer-options
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
[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
[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
docs: Expand production install docs. - Moves Let's Encrypt option for ssl certs above self-signed option. Updates Let's Excrypt instructions to user Certbot (new recommended method). Fixes #1426. - Adds and updates headings for clarity. - Adds new step 6 about configuring authentication (from prod-auth-first-login.html). - Adds emphasis on using `su zulip`, `sudo -u zulip -i`, and `sudo -i` where appropriate. Fixes #1356. Fixes #1245.
2016-07-28 01:38:02 +02:00
install docs: Tighten "create organization" step. The screenshots weren't doing much good without being embedded in the text... and in fact, looking at them for I think the first time, they're badly out of date with the app. So cut them. We might add screenshots later, but on the other hand if we do a good job with the forms themselves, they should be superfluous.
2018-03-03 02:44:53 +01:00
## Step 3: Create a Zulip organization, and log in
docs: Improve install discussion of settings.
2017-02-22 06:15:11 +01:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
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!
docs: Clean up and clarify documentation flow.
2016-08-25 04:01:03 +02:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
:::{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).
:::
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
docs: Edit installation instructions for clarity.
2024-02-15 05:52:44 +01:00
## Getting started with Zulip
install: Go straight through by default. This flips the experimental `--express` option to be the default. We retain the old behavior, where the script exits before `initialize-database`, as an option `--no-init-db`; it might be useful in e.g. a migration scenario (from a Zulip install elsewhere, or another chat system) where the admin wants to set up the database separately. The install instructions are adjusted to match, getting shorter by two steps and a bunch of words. I think this opens up opportunities to refactor the text to simplify things further, too, but leaving that for another commit. Also tweak the "production" test suite to match.
2018-03-03 01:10:51 +01:00
install docs: Consolidate follow-up steps. Now down to just 4 steps! This version tries to prioritize: just two items that we really want all admins to look at even if they aren't already mentally committed to running a big production service and reading all the docs. Namely, the two required in order to really try out Zulip effectively with one's colleagues.
2018-03-03 02:59:10 +01:00
To really see Zulip in action, you'll need to get the people you work
together with using it with you.
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- [Set up outgoing email](email.md) so Zulip can confirm new users'
install docs: Consolidate follow-up steps. Now down to just 4 steps! This version tries to prioritize: just two items that we really want all admins to look at even if they aren't already mentally committed to running a big production service and reading all the docs. Namely, the two required in order to really try out Zulip effectively with one's colleagues.
2018-03-03 02:59:10 +01:00
email addresses and send notifications.
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Learn how to [get your organization started][realm-admin-docs] using
install docs: Consolidate follow-up steps. Now down to just 4 steps! This version tries to prioritize: just two items that we really want all admins to look at even if they aren't already mentally committed to running a big production service and reading all the docs. Namely, the two required in order to really try out Zulip effectively with one's colleagues.
2018-03-03 02:59:10 +01:00
Zulip at its best.
install: Go straight through by default. This flips the experimental `--express` option to be the default. We retain the old behavior, where the script exits before `initialize-database`, as an option `--no-init-db`; it might be useful in e.g. a migration scenario (from a Zulip install elsewhere, or another chat system) where the admin wants to set up the database separately. The install instructions are adjusted to match, getting shorter by two steps and a bunch of words. I think this opens up opportunities to refactor the text to simplify things further, too, but leaving that for another commit. Also tweak the "production" test suite to match.
2018-03-03 01:10:51 +01:00
install docs: Consolidate follow-up steps. Now down to just 4 steps! This version tries to prioritize: just two items that we really want all admins to look at even if they aren't already mentally committed to running a big production service and reading all the docs. Namely, the two required in order to really try out Zulip effectively with one's colleagues.
2018-03-03 02:59:10 +01:00
Learning more:
install: Go straight through by default. This flips the experimental `--express` option to be the default. We retain the old behavior, where the script exits before `initialize-database`, as an option `--no-init-db`; it might be useful in e.g. a migration scenario (from a Zulip install elsewhere, or another chat system) where the admin wants to set up the database separately. The install instructions are adjusted to match, getting shorter by two steps and a bunch of words. I think this opens up opportunities to refactor the text to simplify things further, too, but leaving that for another commit. Also tweak the "production" test suite to match.
2018-03-03 01:10:51 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Subscribe to the [Zulip announcements email
docs: Update links to zulip-announce mailing list. The links we have now redirect to "My groups" and not to our Google group. Also, the RSS feed is no longer supported by Google, so we should no longer link to it. Fixes #19560.
2021-10-15 00:37:27 +02:00
list](https://groups.google.com/g/zulip-announce) for
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
server administrators. This extremely low-traffic list is for
important announcements, including [new
docs: Update links to zulip-announce mailing list. The links we have now redirect to "My groups" and not to our Google group. Also, the RSS feed is no longer supported by Google, so we should no longer link to it. Fixes #19560.
2021-10-15 00:37:27 +02:00
releases](../overview/release-lifecycle.md) and security issues.
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Follow [Zulip on Twitter](https://twitter.com/zulip).
- Learn how to [configure your Zulip server settings](settings.md).
docs: Clean redundant relative links. We previously had a convention of redundantly including the directory in relative links to reduce mistakes when moving content from one file to another. However, these days we have a broken link checker in test-documentation, and after #21237, MyST-Parser will check relative links (including fragments) when you run build-docs. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-24 00:17:21 +01:00
- Learn about [Backups, export and import](export-and-import.md)
contributor docs: Rename "Upgrade or modify Zulip" -> "Upgrade Zulip". Fixes part of #23984.
2023-01-17 04:33:42 +01:00
and [upgrading](upgrade.md) a production Zulip
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
server.
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
docs: Update URLs to use https://zulip.com. We're migrating to using the cleaner zulip.com domain, which involves changing all of our links from ReadTheDocs and other places to point to the cleaner URL.
2020-06-08 23:04:39 +02:00
[realm-admin-docs]: https://zulip.com/help/getting-your-organization-started-with-zulip