mirror of https://github.com/zulip/zulip.git
docs: Clean up and clarify documentation flow.
This commit is contained in:
Tim Abbott
parent
456da49b06
commit
d09b07310d
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue