diff --git a/docs/prod-install.md b/docs/prod-install.md index 037e65b6f2..68d468df01 100644 --- a/docs/prod-install.md +++ b/docs/prod-install.md @@ -3,20 +3,28 @@ Ensure you have an Ubuntu system that satisfies [the installation 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 -Zulip runs over https only and requires ssl certificates in order to work. It -looks for the certificates in `/etc/ssl/private/zulip.key` and -`/etc/ssl/certs/zulip.combined-chain.crt`. +Zulip runs over https only and requires ssl certificates in order to +work. It looks for the certificates in `/etc/ssl/private/zulip.key` +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 -If you have a full qualified domain name and its A record has been updated to -point to the server where you want to install Zulip, you can use [Let's -Encrypt](https://letsencrypt.org/) to generate a valid, properly signed SSL -certificates, for free. +If you have a domain name and you've configured DNS to point to the +server where you want to install Zulip, you can use [Let's +Encrypt](https://letsencrypt.org/) to generate a valid, properly +signed SSL certificates, for free. 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. @@ -52,9 +60,13 @@ renew with this command: ./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 `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 ``` -You will eventually want to get a properly signed SSL certificate -(and note that at present the Zulip desktop app doesn't support -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. +You will eventually want to get a properly signed SSL certificate, but +this will let you finish the installation process. -### 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 possible to finish a Zulip installation that way; just set 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 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 packages via apt. -The Zulip install script is designed to be idempotent, so if it -fails, you can just rerun it after correcting the issue that caused -it to fail. +The Zulip install script is designed to be idempotent, so if it fails, +you can just rerun it after correcting the issue that caused it to +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 @@ -128,19 +135,30 @@ These settings include: - `EXTERNAL_HOST`: the user-accessible Zulip domain name for your Zulip installation. This will be the domain for which you have DNS A records pointing to this server and for which you configured SSL certificates. + - `ZULIP_ADMINISTRATOR`: the email address of the person or team maintaining this installation and who will get support emails. + - `ADMIN_DOMAIN`: the domain for your organization. Usually this is the main 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) -for more detail on configuring authentication mechanisms. +- `AUTHENTICATION_BACKENDS`: a list of enabled authentication + 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 @@ -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 `sudo -u zulip -i`. -The `initialize-database` script will report an error if you did not fill in -all the mandatory settings from `/etc/zulip/settings.py`. +The `initialize-database` script will report an error if you did not +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 complete, and zulip services will be running. -## Step 6: Configure authentication +## Step 6: Subscribe -Depending which [authentication backend](prod-authentication-methods.html) you -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 +Subscribe to low-traffic [the Zulip announcements Google Group](https://groups.google.com/forum/#!forum/zulip-announce) to get 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).