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

182 lines
7.4 KiB
Markdown
Raw Normal View History

docs: Fix various capitalization errors. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-08-11 01:47:54 +02:00
# Production installation
Move production install instructions to new page.
2016-07-12 21:49:44 +02: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
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 installation requirements](../production/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
[experimental Docker image](../production/deployment.html#zulip-in-docker).
Note that if you're developing for Zulip, you should install Zulip's
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
[development environment](../development/overview.md) instead. If
docs: Make the intro to Production Installation less scary.
2019-07-20 00:50:50 +02:00
you're just looking to play around with Zulip and see what it looks like,
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
you can create a test organization at <https://zulip.com/new>.
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: Document installing Zulip from GitHub. This has been unofficially supported for a long time, and is handy for common use cases, so worth documenting.
2018-10-17 00:19:51 +02:00
* If you'd like to verify the download, we
docs: Simplify discussion of sha256sums.
2017-10-18 07:16:37 +02:00
[publish the sha256sums of our release tarballs](https://www.zulip.org/dist/releases/SHA256SUMS.txt).
docs: Document installing Zulip from GitHub. This has been unofficially supported for a long time, and is handy for common use cases, so worth documenting.
2018-10-17 00:19:51 +02:00
* You can also
Revert "docs: Update .html links to .md." This doesn't work without the CommonMark upgrade. This reverts commit c87893feeacaa78315ffc72510afe8e92477f4e8.
2019-04-06 02:58:44 +02:00
[install a pre-release version of Zulip](../production/deployment.html#installing-zulip-from-git)
docs: Make more clear how installing from Git works. The previous discussion made it sound like this did a development environment installation.
2019-01-08 04:16:59 +01: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: 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: 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.
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: 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: 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
[doc-settings]: ../production/settings.md
Revert "docs: Update .html links to .md." This doesn't work without the CommonMark upgrade. This reverts commit c87893feeacaa78315ffc72510afe8e92477f4e8.
2019-04-06 02:58:44 +02:00
[doc-certbot]: ../production/ssl-certificates.html#certbot-recommended
[doc-ssl-manual]: ../production/ssl-certificates.html#manual-install
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
[doc-deployment-options]: ../production/deployment.html#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
script: Add ready-to-run tooling for doing backups. Based on an initial version by Tim Abbott (#11204). Fixes #552.
2019-01-16 03:17:33 +01: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: Merge "Backups" with export-and-import. - Merges the "Backups" section from production/maintain-secure-upgrade.md with existing "Backups" section in production/export-and-import.md. - Cleans up and makes content more clear/explicit. - Adds short missing section on how to use wal-e configuration. - Removes a lot of previously duplicate text explaining the difference between the tools. - Various textual tweaks by tabbott. Fixes #13184 and resolves #293.
2019-09-25 01:58:20 +02:00
[zulip-backups]: ../production/export-and-import.html#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
Otherwise, open the link in a browser. Follow the prompts to set up
your organization, and your own user account as an administrator.
Then, log in!
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
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
running [multiple organizations on the same server](multiple-organizations.md)
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
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: 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
* [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.
* 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
docs: Add new summary section to the release lifecycle page.
2021-05-06 03:24:17 +02:00
* Subscribe to the [Zulip announcements email
list](https://groups.google.com/forum/#!forum/zulip-announce) for
server administrators. This extremely low-traffic list is for
important announcements, including [new
releases](../overview/release-lifecycle.md) and security issues. You
can also use the [RSS
feed](https://groups.google.com/forum/#!aboutgroup/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
* Follow [Zulip on Twitter](https://twitter.com/zulip).
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
* Learn how to [configure your Zulip server settings](settings.md).
docs: Split maintain-secure-upgrade into dedicated docs. * Moves "Management commands" to a top-level section. * Moves "Scalability" as a subsection at the bottom of "Requirements". * Moves "Monitoring" as a subsections at the bottom of "Troubleshooting". * Replaces "API and your Zulip URL" with a link to REST API docs. This documentation text has been irrelevant for some time. * Removes maintain-secure-upgrade from the TOC but the file remains to avoid breaking old links from release blog posts and emails.
2019-11-22 02:07:17 +01:00
* Learn about [Backups, export and import](../production/export-and-import.md)
docs: Merge "Upgrading" with modifying-zulip. Merges the "Upgrades" section from production/maintain-secure-upgrade.md with production/modifying-zulip.md. Contains significant textual changes by tabbott to read more clearly.
2019-10-14 21:40:48 +02:00
and [upgrading](../production/upgrade-or-modify.md) a production Zulip
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
```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
docs: Standardize on PostgreSQL, not Postgres.
2020-10-26 22:27:53 +01:00
PostgreSQL, RabbitMQ, Memcached and Redis.
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
* 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
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.**
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: 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
out! Please provide details like the full traceback from the bottom
of `/var/log/zulip/errors.log` in your report (ideally in a [code
block][code-block]).
[chat-zulip-org]: ../contributing/chat-zulip-org.md
[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