mirror of
https://github.com/zulip/zulip.git
synced 2025-11-04 05:53:43 +00:00
docs: Update documentation to recommend certbot.
This commit is contained in:
Tim Abbott
Greg Price
@@ -21,16 +21,34 @@ su zulip -c /home/zulip/deployments/current/scripts/restart-server
|
||||
|
||||
## Specific settings
|
||||
|
||||
### Domain and Email settings
|
||||
|
||||
`EXTERNAL_HOST`: the user-accessible domain name for your Zulip
|
||||
installation (i.e., what users will type in their web browser). This
|
||||
should of course match the DNS name you configured to point to your
|
||||
server and for which you configured SSL certificates. If you passed
|
||||
`--hostname` to the installer, this will be prefilled with that value.
|
||||
|
||||
`ZULIP_ADMINISTRATOR`: the email address of the person or team
|
||||
maintaining this installation and who will get support and error
|
||||
emails. If you passed `--email` to the installer, this will be
|
||||
prefilled with that value.
|
||||
|
||||
### Authentication Backends
|
||||
|
||||
`AUTHENTICATION_BACKENDS` is a list of enabled authentication mechanisms. By
|
||||
default the email backend is enabled.
|
||||
`AUTHENTICATION_BACKENDS`: Zulip supports a wide range of popular
|
||||
options for authenticating users to your server, including Google
|
||||
Auth, GitHub Auth, LDAP, REMOTE_USER, and more. Note, however, that
|
||||
the default (email) backend must be used when creating a new
|
||||
organization.
|
||||
|
||||
If you want an additional or different authentication backend, you will need to
|
||||
uncomment one or more and then do any additional configuration required for
|
||||
that backend as documented in the `settings.py` file. See
|
||||
the [section on Authentication](../production/authentication-methods.html) for more detail on the available
|
||||
authentication backends and how to configure them.
|
||||
If you want an additional or different authentication backend, you
|
||||
will need to uncomment one or more and then do any additional
|
||||
configuration required for that backend as documented in the
|
||||
`settings.py` file. See the
|
||||
[section on Authentication](../production/authentication-methods.html) for more
|
||||
detail on the available authentication backends and how to configure
|
||||
them.
|
||||
|
||||
### Mobile and desktop apps
|
||||
|
||||
|
||||
@@ -14,21 +14,10 @@ you need:
|
||||
production installation.
|
||||
* 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.
|
||||
For most users, you can just use our handy `--certbot` option to
|
||||
generate the SSL certificate.
|
||||
|
||||
## 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`. 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 need an SSL certificate, see [our SSL certificate
|
||||
documentation](ssl-certificates.html). If you already have an SSL
|
||||
certificate, just install (or symlink) it into place at the above
|
||||
paths, and move on to the next step.
|
||||
|
||||
## Step 2: Download and install latest release
|
||||
## Step 1: Download the latest release
|
||||
|
||||
Download and unpack [the latest built server
|
||||
tarball](https://www.zulip.org/dist/releases/zulip-server-latest.tar.gz)
|
||||
@@ -43,14 +32,20 @@ tar -xf zulip-server-latest.tar.gz
|
||||
If you'd like to verify the download, we
|
||||
[publish the sha256sums of our release tarballs](https://www.zulip.org/dist/releases/SHA256SUMS.txt).
|
||||
|
||||
Then, run the Zulip install script:
|
||||
## Step 2: Install Zulip
|
||||
|
||||
Most users will want Zulip to automatically obtain an SSL certificate
|
||||
for their server using [Certbot](https://certbot.eff.org/). In that
|
||||
case, you can run the installer as follows:
|
||||
|
||||
```
|
||||
sudo -s # If not already root
|
||||
./zulip-server-*/scripts/setup/install
|
||||
sudo -i # If not already root
|
||||
./zulip-server-*/scripts/setup/install --certbot \
|
||||
--email=username@example.com --hostname=zulip.example.com
|
||||
```
|
||||
|
||||
This may take a while to run, since it will install a large number of
|
||||
dependencies.
|
||||
This will take a while to run, since it will install a large number of
|
||||
dependencies from the pypi and npm repositories.
|
||||
|
||||
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
|
||||
@@ -58,6 +53,8 @@ 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.
|
||||
|
||||
#### What the installer does
|
||||
|
||||
The install script does several things:
|
||||
* Creates `zulip` user, which the various Zulip servers will run as,
|
||||
* Creates `/home/zulip/deployments/`, which the Zulip code for this
|
||||
@@ -70,20 +67,18 @@ symbolic link to it.
|
||||
* Configures the various third-party services Zulip uses, including
|
||||
Postgres, RabbitMQ, Memcached and Redis.
|
||||
|
||||
## Step 3: Configure Zulip
|
||||
#### Providing your own SSL certificate
|
||||
|
||||
Configure the Zulip server instance by editing `/etc/zulip/settings.py` and
|
||||
providing values for the mandatory settings, which are all found under the
|
||||
heading `### MANDATORY SETTINGS`. These settings include:
|
||||
If you'd like to use an SSL certificate that you obtained not using
|
||||
Certbot way (e.g. issued by your corporate certificate authority),
|
||||
[our ssl certificate documentation](ssl-certificates.html) covers what
|
||||
you need to do.
|
||||
|
||||
- `EXTERNAL_HOST`: the user-accessible domain name for your
|
||||
Zulip installation (i.e., what users will type in their web
|
||||
browser). This should of course match the DNS name you configured to
|
||||
point to your server and for which you configured SSL certificates.
|
||||
## Step 3: Configure outgoing email
|
||||
|
||||
- `ZULIP_ADMINISTRATOR`: the email address of the person or team
|
||||
maintaining this installation and who will get support and error
|
||||
emails.
|
||||
Configure the Zulip server instance by editing
|
||||
`/etc/zulip/settings.py` to enable your server's ability to send
|
||||
outgoing emails:
|
||||
|
||||
- `EMAIL_HOST`, `EMAIL_HOST_USER`: credentials for an outgoing email
|
||||
(aka "SMTP") server that Zulip can use to send emails. See
|
||||
|
||||
@@ -66,18 +66,22 @@ save yourself the work of upgrading in a few months.
|
||||
#### Domain name
|
||||
|
||||
You should already have a domain name available for your Zulip
|
||||
production instance. In order to generate valid SSL certificates with Let's
|
||||
Encrypt, and to enable other services such as Google Authentication, you'll
|
||||
need to update the domain's A record to point to your production server.
|
||||
production instance. In order to generate valid SSL certificates with
|
||||
Certbot, and to enable other services such as Google Authentication,
|
||||
you'll need to update the domain's A record to point to your
|
||||
production server.
|
||||
|
||||
## Credentials needed
|
||||
|
||||
#### SSL Certificate
|
||||
|
||||
* An SSL certificate for the host you're putting this on (e.g.,
|
||||
zulip.example.com). If you don't have an SSL solution already, read
|
||||
about [getting an SSL certificate for free](ssl-certificates.html) using
|
||||
Let's Encrypt.
|
||||
zulip.example.com). Unless you have your own certificate authority,
|
||||
you should be able to just use the `--certbot` option in the Zulip
|
||||
installer to automatically generate one for free using
|
||||
[Certbot](https://certbot.eff.org/). Additional options are
|
||||
documented in our
|
||||
[SSL certificate documentation](ssl-certificates.html).
|
||||
|
||||
#### Outgoing email
|
||||
|
||||
|
||||
@@ -1,10 +1,23 @@
|
||||
# SSL Certificates
|
||||
# Installing SSL Certificates
|
||||
|
||||
To keep your communications secure, Zulip runs over HTTPS only.
|
||||
You'll need an SSL/TLS certificate. Fortunately, as of 2017 new
|
||||
options can make getting and maintaining a genuine,
|
||||
trusted-by-browsers certificate no longer the chore (nor expense)
|
||||
that it used to be.
|
||||
You'll need an SSL/TLS certificate.
|
||||
|
||||
Fortunately, as of 2017 new options can make getting and maintaining a
|
||||
genuine, trusted-by-browsers certificate no longer the chore (nor
|
||||
expense) that it used to be.
|
||||
|
||||
## Manual install
|
||||
|
||||
Zulip looks for SSL certificate files in `/etc/ssl/private/zulip.key`
|
||||
and `/etc/ssl/certs/zulip.combined-chain.crt`. Because Zulip uses
|
||||
`nginx` as its web server, it [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) it
|
||||
into place at the above paths.
|
||||
|
||||
If not, read on.
|
||||
|
||||
## Using Certbot / Let's Encrypt
|
||||
|
||||
|
||||
Reference in New Issue
Block a user