mirror of https://github.com/zulip/zulip.git
303 lines
11 KiB
Markdown
303 lines
11 KiB
Markdown
# Deployment options
|
|
|
|
The default Zulip installation instructions will install a complete
|
|
Zulip server, with all of the services it needs, on a single machine.
|
|
|
|
For production deployment, however, it's common to want to do
|
|
something more complicated. This page documents the options for doing so.
|
|
|
|
## Installing Zulip from Git
|
|
|
|
To install a development version of Zulip from Git, just clone the Git
|
|
repository from GitHub:
|
|
|
|
```
|
|
# First, install Git if you don't have it installed already
|
|
sudo apt install git
|
|
git clone https://github.com/zulip/zulip.git zulip-server-git
|
|
```
|
|
|
|
and then
|
|
[continue the normal installation instructions](../production/install.html#step-2-install-zulip).
|
|
You can also [upgrade Zulip from Git](../production/upgrade-or-modify.html#upgrading-from-a-git-repository).
|
|
|
|
## Zulip in Docker
|
|
|
|
Zulip has an officially supported, experimental
|
|
[docker image](https://github.com/zulip/docker-zulip). Please note
|
|
that Zulip's [normal installer](../production/install.md) has been
|
|
extremely reliable for years, whereas the Docker image is new and has
|
|
rough edges, so we recommend the normal installer unless you have a
|
|
specific reason to prefer Docker.
|
|
|
|
## Running Zulip's service dependencies on different machines
|
|
|
|
Zulip has full support for each top-level service living on its own
|
|
machine.
|
|
|
|
You can configure remote servers for Postgres, RabbitMQ, Redis,
|
|
in `/etc/zulip/settings.py`; just search for the service name in that
|
|
file and you'll find inline documentation in comments for how to
|
|
configure it.
|
|
|
|
Since some of these services require some configuration on the node
|
|
itself (e.g. installing our `postgres` extensions), we have designed
|
|
the puppet configuration that Zulip uses for installing and upgrading
|
|
configuration to be completely modular.
|
|
|
|
For example, you can install a Zulip rabbitmq server on a machine, you
|
|
can do the following after unpacking a Zulip production release
|
|
tarball:
|
|
|
|
```
|
|
env PUPPET_CLASSES=zulip::base,zulip::apt_repository,zulip::redis ./scripts/setup/install
|
|
```
|
|
|
|
You can see most likely manifests you might want to choose in the list
|
|
of includes in
|
|
[the main manifest for the default all-in-one Zulip server][voyager.pp],
|
|
though it's also possible to subclass some of the lower-level
|
|
manifests defined in that directory if you want to customize. A good
|
|
example of doing this is in the
|
|
[zulip_ops puppet configuration][zulipchat-puppet] that we use as part
|
|
of managing chat.zulip.org and zulipchat.com.
|
|
|
|
### Using Zulip with Amazon RDS as the database
|
|
|
|
You can use DBaaS services like Amazon RDS for the Zulip database.
|
|
The experience is slightly degraded, in that most DBaaS provides don't
|
|
include useful dictionary files in their installations and don't
|
|
provide a way to provide them yourself, resulting in a degraded
|
|
[full-text search](../subsystems/full-text-search.md) experience
|
|
around issues dictionary files are relevant (e.g. stemming).
|
|
|
|
You also need to pass some extra options to the Zulip installer in
|
|
order to avoid it throwing an error when Zulip attempts to configure
|
|
the database's dictionary files for full-text search; the details are
|
|
below.
|
|
|
|
#### Step 1: Setup Zulip
|
|
|
|
Follow the [standard instructions](../production/install.md), with one
|
|
change. When running the installer, pass the `--remote-postgres`
|
|
flag, e.g.:
|
|
|
|
```
|
|
sudo -s # If not already root
|
|
./zulip-server-*/scripts/setup/install --certbot \
|
|
--email=YOUR_EMAIL --hostname=YOUR_HOSTNAME \
|
|
--remote-postgres --postgres-missing-dictionaries
|
|
```
|
|
|
|
The script also installs and starts Postgres on the server by
|
|
default. We don't need it, so run the following command to
|
|
stop and disable the local Postgres server.
|
|
|
|
```
|
|
sudo service postgresql stop
|
|
sudo update-rc.d postgresql disable
|
|
```
|
|
|
|
This complication will be removed in a future version.
|
|
|
|
#### Step 2: Create the Postgres database
|
|
|
|
Access an administrative `psql` shell on your postgres database, and
|
|
run the commands in `scripts/setup/create-db.sql` to:
|
|
|
|
* Create a database called `zulip`.
|
|
* Create a user called `zulip`.
|
|
* Now login with the `zulip` user to create a schema called
|
|
`zulip` in the `zulip` database. You might have to grant `create`
|
|
privileges first for the `zulip` user to do this.
|
|
|
|
Depending on how authentication works for your postgres installation,
|
|
you may also need to set a password for the Zulip user, generate a
|
|
client certificate, or similar; consult the documentation for your
|
|
database provider for the available options.
|
|
|
|
#### Step 3: Configure Zulip to use the Postgres database
|
|
|
|
In `/etc/zulip/settings.py` on your Zulip server, configure the
|
|
following settings with details for how to connect to your postgres
|
|
server. Your database provider should provide these details.
|
|
|
|
* `REMOTE_POSTGRES_HOST`: Name or IP address of the postgres server.
|
|
* `REMOTE_POSTGRES_PORT`: Port on the postgres server.
|
|
* `REMOTE_POSTGRES_SSLMODE`: SSL Mode used to connect to the server.
|
|
|
|
If you're using password authentication, you should specify the
|
|
password of the `zulip` user in /etc/zulip/zulip-secrets.conf as
|
|
follows:
|
|
|
|
```
|
|
postgres_password = abcd1234
|
|
```
|
|
|
|
Now complete the installation by running the following commands.
|
|
|
|
```
|
|
# Ask Zulip installer to initialize the postgres database.
|
|
su zulip -c '/home/zulip/deployments/current/scripts/setup/initialize-database'
|
|
|
|
# And then generate a realm creation link:
|
|
su zulip -c '/home/zulip/deployments/current/manage.py generate_realm_creation_link'
|
|
```
|
|
|
|
## Using an alternate port
|
|
|
|
If you'd like your Zulip server to use an HTTPS port other than 443, you can
|
|
configure that as follows:
|
|
|
|
1. Edit `EXTERNAL_HOST` in `/etc/zulip/settings.py`, which controls how
|
|
the Zulip server reports its own URL, and restart the Zulip server
|
|
with `/home/zulip/deployments/current/scripts/restart-server`.
|
|
1. Add the following block to `/etc/zulip/zulip.conf`:
|
|
|
|
```
|
|
[application_server]
|
|
nginx_listen_port = 12345
|
|
```
|
|
|
|
1. As root, run
|
|
`/home/zulip/deployments/current/scripts/zulip-puppet-apply`. This
|
|
will convert Zulip's main `nginx` configuration file to use your new
|
|
port.
|
|
|
|
We also have documentation for a Zulip server [using HTTP][using-http] for use
|
|
behind reverse proxies.
|
|
|
|
[using-http]: ../production/deployment.html#configuring-zulip-to-allow-http
|
|
|
|
## Putting the Zulip application behind a reverse proxy
|
|
|
|
Zulip is designed to support being run behind a reverse proxy server.
|
|
This section contains notes on the configuration required with
|
|
variable reverse proxy implementations.
|
|
|
|
### Installer options
|
|
|
|
If your Zulip server will not be on the public Internet, we recommend,
|
|
installing with the `--self-signed-cert` option (rather than the
|
|
`--certbot` option), since CertBot requires the server to be on the
|
|
public Internet.
|
|
|
|
#### Configuring Zulip to allow HTTP
|
|
|
|
Depending on your environment, you may want the reverse proxy to talk
|
|
to the Zulip server over HTTP; this can be secure when the Zulip
|
|
server is not directly exposed to the public Internet.
|
|
|
|
After installing the Zulip server as
|
|
[described above](#installer-options), you can configure Zulip to talk
|
|
HTTP as follows:
|
|
|
|
1. Add the following block to `/etc/zulip/zulip.conf`:
|
|
|
|
```
|
|
[application_server]
|
|
http_only = true
|
|
```
|
|
|
|
1. As root, run
|
|
`/home/zulip/deployments/current/scripts/zulip-puppet-apply`. This
|
|
will convert Zulip's main `nginx` configuration file to allow HTTP
|
|
instead of HTTPS.
|
|
|
|
1. Finally, restart the Zulip server, using
|
|
`/home/zulip/deployments/current/scripts/restart-server`.
|
|
|
|
### nginx configuration
|
|
|
|
You can look at our
|
|
[nginx reverse proxy configuration][nginx-loadbalancer] to see an
|
|
example of how to do this properly (the various include files are
|
|
available via the `zulip::nginx` puppet module). Or modify this example:
|
|
|
|
```
|
|
map $http_upgrade $connection_upgrade {
|
|
default upgrade;
|
|
'' close;
|
|
}
|
|
server {
|
|
listen 443 ssl;
|
|
server_name zulip.example.net;
|
|
|
|
ssl on;
|
|
ssl_certificate /path/to/fullchain-cert.pem;
|
|
ssl_certificate_key /path/to/private-key.pem;
|
|
|
|
location / {
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header Host $http_host;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection $connection_upgrade;
|
|
proxy_http_version 1.1;
|
|
proxy_buffering off;
|
|
proxy_read_timeout 20m;
|
|
proxy_pass https://zulip-upstream-host;
|
|
}
|
|
}
|
|
```
|
|
|
|
Don't forget to update `server_name`, `ssl_certificate`,
|
|
`ssl_certificate_key` and `proxy_pass` with propper values.
|
|
|
|
[nginx-proxy-config]: https://github.com/zulip/zulip/blob/master/puppet/zulip/files/nginx/zulip-include-common/proxy
|
|
[nginx-proxy-longpolling-config]: https://github.com/zulip/zulip/blob/master/puppet/zulip/files/nginx/zulip-include-common/proxy_longpolling
|
|
[voyager.pp]: https://github.com/zulip/zulip/blob/master/puppet/zulip/manifests/voyager.pp
|
|
[zulipchat-puppet]: https://github.com/zulip/zulip/tree/master/puppet/zulip_ops/manifests
|
|
[nginx-loadbalancer]: https://github.com/zulip/zulip/blob/master/puppet/zulip_ops/files/nginx/sites-available/loadbalancer
|
|
|
|
### HAProxy configuration
|
|
|
|
If you want to use HAProxy with Zulip, this `backend` config is a good
|
|
place to start.
|
|
|
|
```
|
|
backend zulip
|
|
mode http
|
|
balance leastconn
|
|
http-request set-header X-Client-IP %[src]
|
|
reqadd X-Forwarded-Proto:\ https
|
|
server zulip 10.10.10.10:80 check
|
|
```
|
|
|
|
Since this configuration uses the `http` mode, you will also need to
|
|
[configure Zulip to allow HTTP](#configuring-zulip-to-allow-http) as
|
|
described above.
|
|
|
|
### Other proxies
|
|
|
|
If you're using another reverse proxy implementation, there are few
|
|
things you need to be careful about when configuring it:
|
|
|
|
1. Configure your reverse proxy (or proxies) to correctly maintain the
|
|
`X-Forwarded-For` HTTP header, which is supposed to contain the series
|
|
of IP addresses the request was forwarded through. You can verify
|
|
your work by looking at `/var/log/zulip/server.log` and checking it
|
|
has the actual IP addresses of clients, not the IP address of the
|
|
proxy server.
|
|
|
|
2. Ensure your proxy doesn't interfere with Zulip's use of
|
|
long-polling for real-time push from the server to your users'
|
|
browsers. This [nginx code snippet][nginx-proxy-longpolling-config]
|
|
does this.
|
|
|
|
The key configuration options are, for the `/json/events` and
|
|
`/api/1/events` endpoints:
|
|
|
|
* `proxy_read_timeout 1200;`. It's critical that this be
|
|
significantly above 60s, but the precise value isn't important.
|
|
* `proxy_buffering off`. If you don't do this, your `nginx` proxy may
|
|
return occasional 502 errors to clients using Zulip's events API.
|
|
|
|
3. The other tricky failure mode we've seen with `nginx` reverse
|
|
proxies is that they can load-balance between the IPv4 and IPv6
|
|
addresses for a given hostname. This can result in mysterious errors
|
|
that can be quite difficult to debug. Be sure to declare your
|
|
`upstreams` equivalent in a way that won't do load-balancing
|
|
unexpectedly (e.g. pointing to a DNS name that you haven't configured
|
|
with multiple IPs for your Zulip machine; sometimes this happens with
|
|
IPv6 configuration).
|