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

168 lines
6.6 KiB
Markdown
Raw Normal View History

docs: Improve installation instruction headings. The previous RTD headings were unclear and resulted in some users attempting to install the Zulip production environment for doing development. This clarifies the situation.
2016-12-07 02:34:41 +01:00
# Production Installation
Move production install instructions to new page.
2016-07-12 21:49:44 +02:00
install docs: Fix some small grammar and orthography issues. After editing this file for the previous commit, I couldn't unsee "low-traffic the". So I fixed that, saw more issues, and then just went through the page for everything that was similarly trivial to fix.
2017-07-26 00:49:16 +02:00
Make sure you want to install a Zulip production server. If you'd
docs: Improve installation instruction headings. The previous RTD headings were unclear and resulted in some users attempting to install the Zulip production environment for doing development. This clarifies the situation.
2016-12-07 02:34:41 +01:00
instead like to test or develop a new feature, we recommend the
docs: Update intros to production install pages. We should cut to the chase where we can.
2018-08-21 02:26:50 +02:00
[Zulip development server](../development/overview.html#requirements) instead.
If you just want to play around with Zulip and see what it looks like, you
can create a test organization at <https://zulipchat.com>.
docs: Improve installation instruction headings. The previous RTD headings were unclear and resulted in some users attempting to install the Zulip production environment for doing development. This clarifies the situation.
2016-12-07 02:34:41 +01:00
docs: Document production support for Debian Stretch and Ubuntu Bionic. Fixes #9197.
2018-06-05 17:03:15 +02:00
You'll need an Ubuntu or Debian system that satisfies
install docs: Move requirements tl;dr to requirements doc. This further reduces the wall of text on the install instructions. Simultaneously it lightens up the pressure on this summary to be quite so terse; expand a couple of items into multiple bullets (yet with fewer words!) for greater readability.
2018-03-03 03:12:40 +01:00
[the installation requirements](../production/requirements.html).
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: Simplify install instruction for production environment.
2017-10-18 12:34:56 +02:00
Download and unpack [the latest built server
Replace references to zulip.com/dist with zulip.org/dist. Now that zulip.org has all the files to distribute, there's no reason to still point to the soon-to-be-decommissioned zulip.com/dist.
2017-01-29 02:56:25 +01:00
tarball](https://www.zulip.org/dist/releases/zulip-server-latest.tar.gz)
docs: Collapse install steps 2 and 3 together.
2016-08-25 06:36:07 +02:00
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/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)
Replace references to zulip.com/dist with zulip.org/dist. Now that zulip.org has all the files to distribute, there's no reason to still point to the soon-to-be-decommissioned zulip.com/dist.
2017-01-29 02:56:25 +01:00
wget https://www.zulip.org/dist/releases/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: Simplify discussion of sha256sums.
2017-10-18 07:16:37 +02:00
If you'd like to verify the download, we
[publish the sha256sums of our release tarballs](https://www.zulip.org/dist/releases/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: Warn on development version of install instructions.
2018-01-23 19:52:23 +01:00
```eval_rst
.. only:: unreleased
.. warning::
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`__.
__ https://zulip.readthedocs.io/en/stable/prod-install.html
```
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
To set up Zulip with the most common configuration, you can run the
installer as follows:
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
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
sudo -i # If not already root
./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
```
install docs: Move background details to after main flow too. This further shortens the wall of text inside the instructions. Note that thanks to embedded reST, we now have the power to provide custom anchors at section headings! Which in particular means this link won't break if we later tweak the wording of this heading.
2018-03-03 02:23:07 +01:00
This takes a few minutes to run, as it installs Zulip's dependencies.
For more on what the installer does, [see details below](#installer-details).
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: Move background details to after main flow too. This further shortens the wall of text inside the instructions. Note that thanks to embedded reST, we now have the power to provide custom anchors at section headings! Which in particular means this link won't break if we later tweak the wording of this heading.
2018-03-03 02:23:07 +01:00
If the script gives an error, consult [Troubleshooting](#troubleshooting) below.
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
* `--email=you@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][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` ([docs][doc-settings]) in the Zulip
settings.
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
* `--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.
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
* `--certbot`: With this option, the Zulip installer automatically
obtains an SSL certificate for the server [using Certbot][doc-certbot].
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].
docs: Rename customize.html to settings.html. This is a better description of what this is for.
2018-02-19 18:46:09 +01:00
[doc-settings]: ../production/settings.html
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
[doc-certbot]: ../production/ssl-certificates.html#certbot-recommended
[doc-ssl-manual]: ../production/ssl-certificates.html#manual-install
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
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
On success, the install script prints a link. 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!
docs: Clean up and clarify documentation flow.
2016-08-25 04:01:03 +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
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.html)
if that's what you're planning to do.
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02: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
## Step 4: Configure and use
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.
* [Set up outgoing email](email.html) so Zulip can confirm new users'
email addresses and send notifications.
* Learn how to [get your organization started][realm-admin-docs] using
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
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
* Subscribe to the
docs: Move subscribe instructions to end of install instructions.
2017-08-16 01:25:24 +02:00
[Zulip announcements email list](https://groups.google.com/forum/#!forum/zulip-announce)
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
for server administrators. This extremely low-traffic list is for
important announcements, including new releases and security issues.
* Follow [Zulip on Twitter](https://twitter.com/zulip).
* Learn how to [configure your Zulip server settings](settings.html).
* Learn about [maintaining a production Zulip server](maintain-secure-upgrade.html).
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
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
[realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip
install docs: Move background details to after main flow too. This further shortens the wall of text inside the instructions. Note that thanks to embedded reST, we now have the power to provide custom anchors at section headings! Which in particular means this link won't break if we later tweak the wording of this heading.
2018-03-03 02:23:07 +01:00
```eval_rst
.. _installer-details:
```
## Details: What the installer does
The install script does several things:
* Creates the `zulip` user, which the various Zulip servers will run as.
* Creates `/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/current` as a
symbolic link to it.
* Installs Zulip's various dependencies.
* Configures the various third-party services Zulip uses, including
Postgres, RabbitMQ, Memcached and Redis.
* Initializes Zulip's database.
docs: Add production documentation on deployment options. This describes the basics of installing Zulip in more complex production environments using multiple services. Fixes #1235.
2018-05-22 20:29:33 +02:00
If you'd like to deploy Zulip with these services on different
machines, check out our [deployment options documentation](deployment.html).
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
## Troubleshooting
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
**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.
**The `zulip` user's password.**
By default, the `zulip` user doesn't
docs: Add troubleshooting notice for `su zulip` as the zulip user.
2017-10-20 23:51:19 +02:00
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.
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
**After the install script.**
If you get an error after `scripts/setup/install` completes, check
docs: Add troubleshooting notice for `su zulip` as the zulip user.
2017-10-20 23:51:19 +02:00
the bottom of `/var/log/zulip/errors.log` for a traceback, and consult
docs: Reorganize developer docs to improve navigation. This commit helps reduce clutter on the navigation sidebar. Creates new directories and moves relevant files into them. Modifies index.rst, symlinks, and image paths accordingly. This commit also enables expandable/collapsible navigation items, renames files in docs/development and docs/production, modifies /tools/test-documentation so that it overrides a theme setting, Also updates links to other docs, file paths in the codebase that point to developer documents, and files that should be excluded from lint tests. Note that this commit does not update direct links to zulip.readthedocs.io in the codebase; those will be resolved in an upcoming follow-up commit (it'll be easier to verify all the links once this is merged and ReadTheDocs is updated). Fixes #5265.
2017-11-08 17:55:36 +01:00
the [troubleshooting section](troubleshooting.html) for advice on
docs: Add troubleshooting notice for `su zulip` as the zulip user.
2017-10-20 23:51:19 +02:00
how to debug.
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
**Community.**
If the tips above don't help, please visit
documentation: Migrate all CZO stream links to new stream URL style This includes changes like changing CZO stream URLs from new.20members to 95-new-members.
2018-05-24 22:01:05 +02:00
[#production help](https://chat.zulip.org/#narrow/stream/31-production-help)
docs: Fix some Markdown links missing a close-paren. These were just introduced today.
2017-11-16 20:39:29 +01:00
in the [Zulip development community server](../contributing/chat-zulip-org.html) for
docs: Update links to point to new chat-zulip-org.html.
2017-02-13 01:55:54 +01:00
realtime help or email zulip-help@googlegroups.com with the full
docs: Restructure install guide troubleshooting section.
2017-08-16 02:08:20 +02:00
traceback, and we'll try to help you out! Please provide details like
the full traceback from the bottom of `/var/log/zulip/errors.log` in
your report.