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

181 lines
7.2 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: 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
[Zulip server development environment](../development/overview.html#requirements) instead.
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
You will need an Ubuntu system that satisfies
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 installation requirements](../production/requirements.html). In short,
docs: Update installation docs for new RAM requirements. This is a follow-up to #32.
2017-06-04 08:30:10 +02:00
you need:
install docs: Reduce prose in requirements bullets.
2018-03-03 01:37:53 +01:00
* A dedicated machine or VM.
* A supported OS:
* Ubuntu 16.04 Xenial 64-bit
* Ubuntu 14.04 Trusty 64-bit (not recommended for new installations)
docs: Update installation docs for new RAM requirements. This is a follow-up to #32.
2017-06-04 08:30:10 +02:00
* At least 2GB RAM and 10 GB disk space (4GB and 2 CPUs recommended for 100+ users).
* A DNS name, an SSL certificate, and credentials for sending email.
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
For most users, you can just use our handy `--certbot` option to
generate the SSL certificate.
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
```
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
This will take a while to run, since it will install a large number of
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
dependencies from the PyPI and NPM repositories.
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: 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
docs: Update documentation to recommend certbot.
2017-10-28 02:46:31 +02:00
#### What the installer does
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
The install script does several things:
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
* Creates the `zulip` user, which the various Zulip servers will run as.
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
* Creates `/home/zulip/deployments/`, which the Zulip code for this
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
deployment (and future deployments when you upgrade) goes into. At the
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
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.
docs: Fix a typo in installation docs.
2017-10-20 23:55:16 +02:00
* Configures the various third-party services Zulip uses, including
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
Postgres, RabbitMQ, Memcached and Redis.
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
* Initializes Zulip's database.
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
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
#### Troubleshooting install failures
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.
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: 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
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.
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: 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
## Step 3: Create a Zulip organization and log in
docs: Improve install discussion of settings.
2017-02-22 06:15:11 +01:00
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
When the install script successfully completes, it prints a secure
one-time-use link that allows creation of a new Zulip organization on
your server.
docs: Clean up and clarify documentation flow.
2016-08-25 04:01:03 +02:00
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
Open that link with your web browser. You'll see the "Create
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
organization" page ([screenshot here](../_static/zulip-create-realm.png)).
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
Enter your email address and click *Create organization*.
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
You'll be prompted to finish setting up your organization, and your
own user account as the initial administrator of the organization
([screenshot here](../_static/zulip-create-user-and-org.png)).
Complete this form and log in!
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
**Congratulations!** You are logged in as an organization
docs: Remove discussion of community organizations. This significantly simplifies the page, and they don't exist anymore anyway.
2017-08-16 02:05:02 +02:00
administrator for your new Zulip organization.
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
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
## Step 4: Configure outgoing email
Zulip needs to be able to send email in order to confirm new users'
email addresses, and to send email notifications. You'll need to
provide Zulip with credentials on an email server it can use for
outgoing messages.
See [our guide for outgoing email](email.html) for detailed
instructions, including references to free outgoing-email services if
you don't have one already. You'll set the host and username in
`/etc/zulip/settings.py` and the password in
`/etc/zulip/zulip-secrets.conf`, then restart Zulip to pick up the new
configuration.
When you're done, [be sure to
test](email.html#testing-and-troubleshooting) your new email
configuration.
## Step 5: Next steps
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
docs: Move subscribe instructions to end of install instructions.
2017-08-16 01:25:24 +02:00
* Subscribe to the extremely low-traffic
[Zulip announcements email list](https://groups.google.com/forum/#!forum/zulip-announce)
to get important announcements for Zulip server administrators about
new releases, security issues, etc.
* [Follow Zulip on Twitter](https://twitter.com/zulip) to get Zulip news.
docs: Improve install guide outgoing links.
2017-08-16 02:09:19 +02:00
* [Learn how to setup your new Zulip organization][realm-admin-docs].
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
* [Learn how configure your Zulip server settings](settings.html).
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
* [Learn about maintaining a production Zulip server](../production/maintain-secure-upgrade.html).
docs: Merge prod-auth-first-login into main installation page.
2016-08-25 06:29:36 +02:00
## Troubleshooting
docs: Add troubleshooting notice for `su zulip` as the zulip user.
2017-10-20 23:51:19 +02:00
* The `zulip` user's password. By default, the `zulip` user doesn't
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.
* If you get an error after `scripts/setup/install` completes, check
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.
* If that doesn't help, please visit
docs: Rename installation help -> production help.
2017-02-13 02:04:05 +01:00
[#production help](https://chat.zulip.org/#narrow/stream/production.20help)
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.
docs: Highlight getting started guide more strongly.
2017-06-08 22:28:51 +02:00
[realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip