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

docs: Clean up and clarify documentation flow.

This commit is contained in:
Tim Abbott 2016-08-24 19:01:03 -07:00
parent 456da49b06
commit d09b07310d
1 changed files with 56 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
docs/prod-install.md
View File

@ -3,20 +3,28 @@
Ensure you have an Ubuntu system that satisfies [the installation Ensure you have an Ubuntu system that satisfies [the installation
requirements](prod-requirements.html). requirements](prod-requirements.html).
Prior to installing Zulip, you should have an Ubuntu 14.04 Trusty 64-bit server instance, with at least 4GB RAM, 2 CPUs, and 10 GB disk space. You should also have a domain name available and have updated its A record to point to this server. Prior to installing Zulip, you should have an Ubuntu 14.04 Trusty
64-bit server instance, with at least 4GB RAM, 2 CPUs, and 10 GB disk
space. You should also have a domain name available and have updated
its DNS record to point to the server.
## Step 1: Install SSL Certificates ## Step 1: Install SSL Certificates
Zulip runs over https only and requires ssl certificates in order to work. It Zulip runs over https only and requires ssl certificates in order to
looks for the certificates in `/etc/ssl/private/zulip.key` and work. It looks for the certificates in `/etc/ssl/private/zulip.key`
`/etc/ssl/certs/zulip.combined-chain.crt`. and `/etc/ssl/certs/zulip.combined-chain.crt`. Note that Zulip uses
`nginx` as its webserver and thus [expects a chained certificate
bundle](http://nginx.org/en/docs/http/configuring_https_servers.html)
If you already have an SSL certificate, just install (or symlink) them
into place at the above paths, and move on to the next step.
### Using Let's Encrypt ### Using Let's Encrypt
If you have a full qualified domain name and its A record has been updated to If you have a domain name and you've configured DNS to point to the
point to the server where you want to install Zulip, you can use [Let's server where you want to install Zulip, you can use [Let's
Encrypt](https://letsencrypt.org/) to generate a valid, properly signed SSL Encrypt](https://letsencrypt.org/) to generate a valid, properly
certificates, for free. signed SSL certificates, for free.
Run all of these commands as root. If you're not already logged in as root, use Run all of these commands as root. If you're not already logged in as root, use
`sudo -i` to start an interactive root shell. `sudo -i` to start an interactive root shell.
@ -52,9 +60,13 @@ renew with this command:
./certbot-auto renew ./certbot-auto renew
``` ```
### Using a self-signed certificate ### Generating a self-signed certificate
If you aren't able to use Let's Encrypt, you can generate a self-signed ssl certificate. If you aren't able to use Let's Encrypt, you can generate a
self-signed ssl certificate. We recommend getting a real certificate
using LetsEncrypt over this approach because your browser (and some of
the Zulip clients) will complain when connecting to your server that
the certificate isn't signed.
Run all of these commands as root. If you're not already logged in as root, use Run all of these commands as root. If you're not already logged in as root, use
`sudo -i` to start an interactive root shell. `sudo -i` to start an interactive root shell.
@ -71,23 +83,16 @@ cp zulip.key /etc/ssl/private/zulip.key
cp zulip.combined-chain.crt /etc/ssl/certs/zulip.combined-chain.crt cp zulip.combined-chain.crt /etc/ssl/certs/zulip.combined-chain.crt
``` ```
You will eventually want to get a properly signed SSL certificate You will eventually want to get a properly signed SSL certificate, but
(and note that at present the Zulip desktop app doesn't support this will let you finish the installation process.
self-signed certificates), but this will let you finish the
installation process. When you do get an actual certificate, you
will need to install as /etc/ssl/certs/zulip.combined-chain.crt the
full certificate authority chain, not just the certificate; see the
section on "SSL certificate chains" [in the nginx
docs](http://nginx.org/en/docs/http/configuring_https_servers.html)
for how to do this.
### If you are using a self-signed certificate with an IP address (no fqdn) ### If you are using a self-signed certificate with an IP address (no domain)
Finally, if you want to proceed with just an IP address, it is Finally, if you want to proceed with just an IP address, it is
possible to finish a Zulip installation that way; just set possible to finish a Zulip installation that way; just set
EXTERNAL_HOST to be the IP address. EXTERNAL_HOST to be the IP address.
## Step 2: Download and uppack latest release ## Step 2: Download and unpack latest release
Download [the latest built server Download [the latest built server
tarball](https://www.zulip.com/dist/releases/zulip-server-latest.tar.gz) and tarball](https://www.zulip.com/dist/releases/zulip-server-latest.tar.gz) and
@ -113,9 +118,11 @@ Run all of these commands as root. If you're not already logged in as root, use
This may take a while to run, since it will install a large number of This may take a while to run, since it will install a large number of
packages via apt. packages via apt.
The Zulip install script is designed to be idempotent, so if it The Zulip install script is designed to be idempotent, so if it fails,
fails, you can just rerun it after correcting the issue that caused you can just rerun it after correcting the issue that caused it to
it to fail. fail. Also note that it automatically logs a transcript to
`/var/log/zulip/install.log`; please include a copy of that file in
any bug reports.
## Step 4: Configure Zulip ## Step 4: Configure Zulip
@ -128,19 +135,30 @@ These settings include:
- `EXTERNAL_HOST`: the user-accessible Zulip domain name for your Zulip - `EXTERNAL_HOST`: the user-accessible Zulip domain name for your Zulip
installation. This will be the domain for which you have DNS A records installation. This will be the domain for which you have DNS A records
pointing to this server and for which you configured SSL certificates. pointing to this server and for which you configured SSL certificates.
- `ZULIP_ADMINISTRATOR`: the email address of the person or team maintaining - `ZULIP_ADMINISTRATOR`: the email address of the person or team maintaining
this installation and who will get support emails. this installation and who will get support emails.
- `ADMIN_DOMAIN`: the domain for your organization. Usually this is the main - `ADMIN_DOMAIN`: the domain for your organization. Usually this is the main
domain used in your organization's email addresses. domain used in your organization's email addresses.
- `AUTHENTICATION_BACKENDS`: a list of enabled authentication mechanisms.
You'll need to enable at least one authentication mechanism by uncommenting
its corresponding line.
- `EMAIL_*` and `DEFAULT_FROM_EMAIL`: Regardless of which authentication
backends you enable, you must provide settings for an outgoing SMTP server so
Zulip can send emails when needed.
See the [section on Authentication](prod-auth-first-login.html) - `AUTHENTICATION_BACKENDS`: a list of enabled authentication
for more detail on configuring authentication mechanisms. mechanisms. You'll need to enable at least one authentication
mechanism by uncommenting its corresponding line, and then also do
any additional configuration required for that backend as documented
in the `settings.py` file. See the [section on
Authentication](prod-auth-first-login.html) for more detail on the
available authentication backends and how to configure them.
- `EMAIL_*`, `DEFAULT_FROM_EMAIL`, and `NOREPLY_EMAIL_ADDRESS`:
Regardless of which authentication backends you enable, you must
provide settings for an outgoing SMTP server so Zulip can send
emails when needed. We highly recommend testing your configuration
using `manage.py send_test_email` to confirm your outgoing email
configuration is working correctly.
- `ALLOWED_HOSTS`: Replace `*` with the fully qualified DNS name for
your Zulip server here.
## Step 5: Run database initialization ## Step 5: Run database initialization
@ -155,44 +173,17 @@ it need to be run by the `zulip` user. You can do this by running each command
with `su zulip -c` or by starting an interactive shell as the zulip user with with `su zulip -c` or by starting an interactive shell as the zulip user with
`sudo -u zulip -i`. `sudo -u zulip -i`.
The `initialize-database` script will report an error if you did not fill in The `initialize-database` script will report an error if you did not
all the mandatory settings from `/etc/zulip/settings.py`. fill in all the mandatory settings from `/etc/zulip/settings.py`. It
is safe to rerun it after correcting the problem if that happens.
Once this script completes successfully, the main installation process will be Once this script completes successfully, the main installation process will be
complete, and zulip services will be running. complete, and zulip services will be running.
## Step 6: Configure authentication ## Step 6: Subscribe
Depending which [authentication backend](prod-authentication-methods.html) you Subscribe to low-traffic [the Zulip announcements Google
would like to use, you will need to do some additional setup documented in the
`settings.py` template:
* For Google authentication, follow the configuration instructions around
`GOOGLE_OAUTH2_CLIENT_ID` and `GOOGLE_CLIENT_ID`.
* For GitHub authentication, follow the instructions around
`SOCIAL_AUTH_GITHUB_KEY`.
Regardless of which authentication backends you enable, **you must provide
settings for an outgoing SMTP server** so Zulip can send emails when needed.
Zulip uses Django's standard EmailBackend, so if you're having issues
configuring email, try their
[documentation](https://docs.djangoproject.com/en/1.8/topics/email/). You can
use `./manage.py send_test_email username@example.com` to test whether you've
successfully configured outgoing SMTP.
For a complete list of authentication backends supported, read [Authentication
Methods](prod-authentication-methods.html) and take a look at
`/etc/zulip/settings.py` for details about how to cofigure each.
Once you have configured authentication, you should be able to log in. Read
[Authentication and logging into Zulip the first
time](prod-auth-first-login.html) for details.
## Step 7: Subscribe
Subscribe to [the Zulip announcements Google
Group](https://groups.google.com/forum/#!forum/zulip-announce) to get Group](https://groups.google.com/forum/#!forum/zulip-announce) to get
announcements about new releases, security issues, etc. announcements about new releases, security issues, etc.
Congratulations! Next: [Authentication and logging into Zulip the first time](prod-auth-first-login.html). Congratulations! Next: [Logging in and creating users](prod-auth-first-login.html).