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

197 lines
8.1 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: 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
## Before you begin
To install a Zulip server, you'll need an Ubuntu or Debian system that satisfies
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
[the installation requirements](requirements.md). Alternatively,
docs: Make the intro to Production Installation less scary.
2019-07-20 00:50:50 +02:00
you can use a preconfigured
docs: Use our Digital Ocean marketplace referral code.
2021-04-20 19:45:26 +02:00
[DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26), or
docs: Make the intro to Production Installation less scary.
2019-07-20 00:50:50 +02:00
Zulip's
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
[experimental Docker image](deployment.md#zulip-in-docker).
docs: Make the intro to Production Installation less scary.
2019-07-20 00:50:50 +02:00
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
### Should I follow this installation guide?
- If you are just looking to play around with Zulip and see what it looks like,
you can create a test Zulip Cloud organization at <https://zulip.com/new>.
- If you are deciding between self-hosting Zulip and signing up for [Zulip Cloud](https://zulip.com/plans/),
docs: Fix typo. We don't suggest self-hosing, unless via a sprinkler in warm weather.
2022-04-04 23:09:59 +02:00
our [self-hosting overview](https://zulip.com/self-hosting/) and [guide to
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
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.
- If you're developing for Zulip, you should follow the instructions
to install Zulip's [development environment](../development/overview.md).
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: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- If you'd like to verify the download, we
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
[publish the sha256sums of our release tarballs](https://download.zulip.com/server/SHA256SUMS.txt).
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- You can also
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
[install a pre-release version of Zulip](deployment.md#installing-zulip-from-git)
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
using code from our [repository on GitHub](https://github.com/zulip/zulip/).
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: 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: 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
```
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.
docs: Replace manual fragment with automatic heading fragment. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-25 00:09:58 +01:00
For more on what the installer does, [see details below](#details-what-the-installer-does).
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
docs: Clarify --email installation option.
2023-01-05 20:34:12 +01:00
- `--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
<support@example.com>". This becomes `ZULIP_ADMINISTRATOR`
([docs][doc-settings]) in the Zulip 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: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- `--hostname=zulip.example.com`: The user-accessible domain name for
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
this Zulip server, i.e., what users will type in their web browser.
This becomes `EXTERNAL_HOST` ([docs][doc-settings]) in the Zulip
settings.
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: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- `--certbot`: With this option, the Zulip installer automatically
docs: Extend Certbot troubleshooting documentation. This should help folks who have problems with Certbot renewal; we had a couple reported this week which I think were both caused by firewall issues.
2021-11-01 19:31:40 +01:00
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].
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: 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
You can see the more advanced installer options in our [deployment options][doc-deployment-options]
documentation.
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: 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: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
On success, the install script prints a link. If you're [restoring a
docs: Remove HipChat migration guide. As of Feb 15th 2019, Hipchat Cloud and Stride have reached End Of Life and are no longer supported by Atlassian. Since it is almost 2 years now we can remove the migration guides.
2020-12-23 08:16:19 +01:00
backup][zulip-backups] or importing your data from [Slack][slack-import],
or another Zulip server, you should stop here
docs: Fix a few typos in documentation.
2019-03-27 19:51:22 +01:00
and return to the import instructions.
docs: Advertise HipChat/Slack import tools in installer docs. This should help avoid confusion about when to use the import tools.
2019-01-17 00:14:13 +01: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
[slack-import]: https://zulip.com/help/import-from-slack
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
[zulip-backups]: export-and-import.md#backups
docs: Advertise HipChat/Slack import tools in installer docs. This should help avoid confusion about when to use the import tools.
2019-01-17 00:14:13 +01:00
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
Otherwise, open the link in a browser. Follow the prompts to set up
docs: Advertise HipChat/Slack import tools in installer docs. This should help avoid confusion about when to use the import tools.
2019-01-17 00:14:13 +01:00
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
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
The link is a secure one-time-use link. If you need another
docs: Rewrap to avoid line breaks in inline code spans. This works around https://github.com/prettier/prettier/issues/11372. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-09-08 00:23:24 +02:00
later, you can generate a new one by running
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
`manage.py generate_realm_creation_link` on the server. See also our
docs: Rewrap to avoid line breaks in inline code spans. This works around https://github.com/prettier/prettier/issues/11372. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-09-08 00:23:24 +02:00
doc on running [multiple organizations on the same
server](multiple-organizations.md) 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.
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
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 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
## Details: What the installer does
The install script does several things:
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
- Creates the `zulip` user, which the various Zulip servers will run as.
- Creates `/home/zulip/deployments/`, which the Zulip code for this
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
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.
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Installs Zulip's various dependencies.
- Configures the various third-party services Zulip uses, including
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
PostgreSQL, RabbitMQ, Memcached and Redis.
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Initializes Zulip's database.
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
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
docs: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
machines, check out our [deployment options documentation](deployment.md).
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
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.**
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
The Zulip install script is designed to be idempotent. This means
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
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
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
`/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
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
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
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
up, but that's up to you as the system administrator). Most people
docs: Add troubleshooting notice for `su zulip` as the zulip user.
2017-10-20 23:51:19 +02:00
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: Reduce the number of apparently broken links on github. - Updated 260+ links from ".html" to ".md" to reduce the number of issues reported about hyperlinks not working when viewing docs on Github. - Removed temporary workaround that suppressed all warnings reported by sphinx build for every link ending in ".html". Details: The recent upgrade to recommonmark==0.5.0 supports auto-converting ".md" links to ".html" so that the resulting HTML output is correct. Notice that links pointing to a heading i.e. "../filename.html#heading", were not updated because recommonmark does not auto-convert them. These links do not generate build warnings and do not cause any issues. However, there are about ~100 such links that might still get misreported as broken links. This will be a follow-up issue. Background: docs: pip upgrade recommonmark and CommonMark #13013 docs: Allow .md links between doc pages #11719 Fixes #11087.
2019-09-30 19:37:56 +02:00
the [troubleshooting section](troubleshooting.md) 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.
docs: Clean up installer troubleshooting help guide. * Remove references to the defunct zulip-help Google Group. * Mention how to create a code block. * Use nicer markdown syntax for links.
2021-04-01 21:08:49 +02:00
**Community.** If the tips above don't help, please visit [#production
help][production-help] in the [Zulip development community
server][chat-zulip-org] for realtime help, and we'll try to help you
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
out! Please provide details like the full traceback from the bottom
docs: Clean up installer troubleshooting help guide. * Remove references to the defunct zulip-help Google Group. * Mention how to create a code block. * Use nicer markdown syntax for links.
2021-04-01 21:08:49 +02:00
of `/var/log/zulip/errors.log` in your report (ideally in a [code
block][code-block]).
external links: Migrate the rest of /developer-community links. We recently changed /developer-community to /development-community. Now that this change is in production, we can also migrate the external links in our ReadTheDocs documentation.
2021-12-09 20:15:18 +01:00
[chat-zulip-org]: https://zulip.com/development-community/
docs: Clean up installer troubleshooting help guide. * Remove references to the defunct zulip-help Google Group. * Mention how to create a code block. * Use nicer markdown syntax for links.
2021-04-01 21:08:49 +02:00
[production-help]: https://chat.zulip.org/#narrow/stream/31-production-help
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
[code-block]: https://zulip.com/help/code-blocks