mirror of
https://github.com/zulip/zulip.git
synced 2025-11-03 21:43:21 +00:00
docs: Merge "Upgrading" with modifying-zulip.
Merges the "Upgrades" section from production/maintain-secure-upgrade.md with production/modifying-zulip.md. Contains significant textual changes by tabbott to read more clearly.
This commit is contained in:
David Rosa
Tim Abbott
2
docs/_templates/layout.html
vendored
2
docs/_templates/layout.html
vendored
@@ -5,7 +5,7 @@
|
||||
# version e.g. to say that something is likely to have changed.
|
||||
# For more info see: https://www.sphinx-doc.org/en/master/templating.html
|
||||
-->
|
||||
{% if (pagename == "production/email-gateway" or pagename == "production/modifying-zulip") and release.endswith('+git') %}
|
||||
{% if (pagename == "production/email-gateway" or pagename == "production/upgrade-or-modify") and release.endswith('+git') %}
|
||||
<!--
|
||||
# email-gateway.html page doesn't exist in the stable documentation yet.
|
||||
# This temporary workaround prevents CircleCI failure and should be removed after the next release.
|
||||
|
||||
@@ -43,7 +43,7 @@ in bursts.
|
||||
readable style.
|
||||
- We merged significant preparatory work for supporting RHEL/CentOS in
|
||||
production. We're now interested in beta testers for this feature.
|
||||
- Added [new documentation](../production/modifying-zulip.md) on
|
||||
- Added [new documentation](../production/upgrade-or-modify.html#modifying-zulip) on
|
||||
maintaining a fork of Zulip.
|
||||
- Added new `streams:public` search operator that searches the public
|
||||
history of all streams in the organization (even before you joined).
|
||||
@@ -440,7 +440,7 @@ Zulip installations; it has minimal changes for existing servers.
|
||||
phase of the upgrade closely, we recommend
|
||||
[running them first manually](../production/expensive-migrations.md)
|
||||
and as well as the usual trick of
|
||||
[doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-system-updates).
|
||||
[doing an apt upgrade first](../production/upgrade-or-modify.html#applying-system-updates).
|
||||
|
||||
**Full feature changelog:**
|
||||
- Added an organization setting for message deletion time limits.
|
||||
@@ -818,7 +818,7 @@ Backend and scaling
|
||||
phase of the upgrade closely, we recommend
|
||||
[running them first manually](../production/expensive-migrations.md) and as well
|
||||
as the usual trick of
|
||||
[doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-system-updates).
|
||||
[doing an apt upgrade first](../production/upgrade-or-modify.html#applying-system-updates).
|
||||
|
||||
* We've removed support for an uncommon legacy deployment model where
|
||||
a Zulip server served multiple organizations on the same domain.
|
||||
|
||||
@@ -19,7 +19,7 @@ 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/maintain-secure-upgrade.html#upgrading-from-a-git-repository).
|
||||
You can also [upgrade Zulip from Git](../production/upgrade-or-modify.html#upgrading-from-a-git-repository).
|
||||
|
||||
## Zulip in Docker
|
||||
|
||||
|
||||
@@ -338,7 +338,7 @@ cd /home/zulip/deployments/current
|
||||
This could take several minutes to run depending on how much data you're
|
||||
importing.
|
||||
|
||||
[upgrade-zulip-from-git]: ../production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: ../production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
|
||||
#### Import options
|
||||
|
||||
|
||||
@@ -11,6 +11,7 @@ Zulip in Production
|
||||
settings
|
||||
mobile-push-notifications
|
||||
maintain-secure-upgrade
|
||||
upgrade-or-modify
|
||||
security-model
|
||||
authentication-methods
|
||||
export-and-import
|
||||
@@ -20,4 +21,3 @@ Zulip in Production
|
||||
email
|
||||
deployment
|
||||
email-gateway
|
||||
modifying-zulip
|
||||
|
||||
@@ -109,7 +109,9 @@ for server administrators. This extremely low-traffic list is for
|
||||
important announcements, including new releases and security issues.
|
||||
* Follow [Zulip on Twitter](https://twitter.com/zulip).
|
||||
* Learn how to [configure your Zulip server settings](settings.md).
|
||||
* Learn about [maintaining a production Zulip server](maintain-secure-upgrade.md).
|
||||
* Learn about [maintaining](../production/maintain-secure-upgrade.md)
|
||||
and [upgrading](../production/upgrade-or-modify.md) a production Zulip
|
||||
server.
|
||||
|
||||
[realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip
|
||||
|
||||
|
||||
@@ -1,11 +1,8 @@
|
||||
# Secure, maintain, and upgrade
|
||||
# Maintain, secure, and upgrade
|
||||
|
||||
This page covers topics that will help you maintain a healthy, up-to-date, and
|
||||
secure Zulip installation, including:
|
||||
|
||||
- [Upgrading](#upgrading)
|
||||
- [Upgrading from a git repository](#upgrading-from-a-git-repository)
|
||||
- [Upgrading the operating system](#upgrading-the-operating-system)
|
||||
- [Monitoring](#monitoring)
|
||||
- [Scalability](#scalability)
|
||||
- [Management commands](#management-commands)
|
||||
@@ -13,360 +10,8 @@ secure Zulip installation, including:
|
||||
You may also want to read this related content:
|
||||
|
||||
- [Security Model](../production/security-model.md)
|
||||
|
||||
## Upgrading
|
||||
|
||||
**We recommend reading this entire section before doing your first
|
||||
upgrade.**
|
||||
|
||||
To upgrade to a new version of the zulip server, download the appropriate
|
||||
release tarball from <https://www.zulip.org/dist/releases/>.
|
||||
|
||||
You also have the option of creating your own release tarballs from a
|
||||
copy of the [zulip.git repository](https://github.com/zulip/zulip)
|
||||
using `tools/build-release-tarball` or upgrade Zulip
|
||||
[to a version in a Git repository directly](#upgrading-from-a-git-repository).
|
||||
|
||||
Next, run as root:
|
||||
|
||||
```
|
||||
/home/zulip/deployments/current/scripts/upgrade-zulip zulip-server-VERSION.tar.gz
|
||||
```
|
||||
|
||||
The upgrade process will shut down the Zulip service and then run `apt-get upgrade`, a
|
||||
puppet apply, any database migrations, and then bring the Zulip service back
|
||||
up. Upgrading will result in some brief downtime for the service, which should be
|
||||
under 30 seconds unless there is an expensive transition involved. Unless you
|
||||
have tested the upgrade in advance, we recommend doing upgrades at off hours.
|
||||
|
||||
(Note that there are
|
||||
[separate instructions for upgrading Zulip if you're using Docker][docker-upgrade].)
|
||||
|
||||
[docker-upgrade]: https://github.com/zulip/docker-zulip#upgrading-the-zulip-container
|
||||
|
||||
### Preserving local changes to configuration files
|
||||
|
||||
**Warning**: If you have modified configuration files installed by
|
||||
Zulip (e.g. the nginx configuration), the Zulip upgrade process will
|
||||
overwrite your configuration when it does the `puppet apply`.
|
||||
|
||||
You can test whether this will happen assuming no upstream changes to
|
||||
the configuration using `scripts/zulip-puppet-apply` (without the
|
||||
`-f` option), which will do a test puppet run and output and changes
|
||||
it would make. Using this list, you can save a copy of any files
|
||||
that you've modified, do the upgrade, and then restore your
|
||||
configuration.
|
||||
|
||||
That said, Zulip's configuration files are designed to be flexible
|
||||
enough for a wide range of installations, from a small self-hosted
|
||||
system to Zulip Cloud. Before making local changes to a configuration
|
||||
file, first check whether there's an option supported by
|
||||
`/etc/zulip/zulip.conf` for the customization you need. And if you
|
||||
need to make local modifications, please report the issue so that we
|
||||
can make the Zulip puppet configuration flexible enough to handle your
|
||||
setup.
|
||||
|
||||
#### nginx configuration changes
|
||||
|
||||
If you need to modify Zulip's `nginx` configuration, we recommend
|
||||
first attempting to add configuration to `/etc/nginx/conf.d` or
|
||||
`/etc/nginx/zulip-include/app.d`; those directories are designed for
|
||||
custom configuration.
|
||||
|
||||
### Troubleshooting with the upgrade log
|
||||
|
||||
The Zulip upgrade script automatically logs output to
|
||||
`/var/log/zulip/upgrade.log`. Please use those logs to include output
|
||||
that shows all errors in any bug reports.
|
||||
|
||||
After the upgrade, we recommend checking `/var/log/zulip/errors.log`
|
||||
to confirm that your users are not experiencing errors after the
|
||||
upgrade.
|
||||
|
||||
### Rolling back to a prior version
|
||||
|
||||
The Zulip upgrade process works by creating a new deployment under
|
||||
`/home/zulip/deployments/` containing a complete copy of the Zulip server code,
|
||||
and then moving the symlinks at `/home/zulip/deployments/{current,last,next}`
|
||||
as part of the upgrade process.
|
||||
|
||||
This means that if the new version isn't working,
|
||||
you can quickly downgrade to the old version by running
|
||||
`/home/zulip/deployments/last/scripts/restart-server`, or to an
|
||||
earlier previous version by running
|
||||
`/home/zulip/deployments/DATE/scripts/restart-server`. The
|
||||
`restart-server` script stops any running Zulip server, and starts
|
||||
the version corresponding to the `restart-server` path you call.
|
||||
|
||||
### Updating settings
|
||||
|
||||
If required, you can update your settings by editing `/etc/zulip/settings.py`
|
||||
and then run `/home/zulip/deployments/current/scripts/restart-server` to
|
||||
restart the server.
|
||||
|
||||
### Applying system updates
|
||||
|
||||
The Zulip upgrade script will automatically run `apt-get update` and
|
||||
then `apt-get upgrade`, to make sure you have any new versions of
|
||||
dependencies (this will also update system packages). We assume that
|
||||
you will install security updates from `apt` regularly, according to
|
||||
your usual security practices for a production server.
|
||||
|
||||
If you'd like to minimize downtime when installing a Zulip server
|
||||
upgrade, you may want to do an `apt-get upgrade` (and then restart the
|
||||
server and check everything is working) before running the Zulip
|
||||
upgrade script.
|
||||
|
||||
There's one `apt` package to be careful about: upgrading `postgresql`
|
||||
while the server is running may result in an outage (basically,
|
||||
`postgresql` might stop accepting new queries but refuse to shut down
|
||||
while waiting for connections from the Zulip server to shut down).
|
||||
While this only happens sometimes, it can be hard to fix for someone
|
||||
who isn't comfortable managing a `postgresql` database [1]. You can
|
||||
avoid that possibility with the following procedure (run as root):
|
||||
|
||||
```
|
||||
apt-get update
|
||||
supervisorctl stop all
|
||||
apt-get upgrade -y
|
||||
supervisorctl start all
|
||||
```
|
||||
|
||||
[1] If this happens to you, just stop the Zulip server, restart
|
||||
postgres, and then start the Zulip server again, and you'll be back in
|
||||
business.
|
||||
|
||||
#### Disabling unattended upgrades
|
||||
|
||||
**Important**: We recommend that you
|
||||
[disable Ubuntu's unattended-upgrades][disable-unattended-upgrades],
|
||||
and instead install apt upgrades manually. With unattended upgrades
|
||||
enabled, the moment a new Postgres release is published, your Zulip
|
||||
server will have its postgres server upgraded (and thus restarted).
|
||||
|
||||
When one of the services Zulip depends on (postgres, memcached, redis,
|
||||
rabbitmq) is restarted, that services will disconnect everything using
|
||||
them (like the Zulip server), and every operation that Zulip does
|
||||
which uses that service will throw an exception (and send you an error
|
||||
report email). These apparently "random errors" can be confusing and
|
||||
might cause you to worry incorrectly about the stability of the Zulip
|
||||
software, which in fact the problem is that Ubuntu automatically
|
||||
upgraded and then restarted key Zulip dependencies.
|
||||
|
||||
Instead, we recommend installing updates for these services manually,
|
||||
and then restarting the Zulip server with
|
||||
`/home/zulip/deployments/current/scripts/restart-server` afterwards.
|
||||
|
||||
[disable-unattended-upgrades]: https://linoxide.com/ubuntu-how-to/enable-disable-unattended-upgrades-ubuntu-16-04/
|
||||
|
||||
### API and your Zulip URL
|
||||
|
||||
To use the Zulip API with your Zulip server, you will need to use the
|
||||
API endpoint of e.g. `https://zulip.example.com/api`. Our Python
|
||||
API example scripts support this via the
|
||||
`--site=https://zulip.example.com` argument. The API bindings
|
||||
support it via putting `site=https://zulip.example.com` in your
|
||||
.zuliprc.
|
||||
|
||||
Every Zulip integration supports this sort of argument (or e.g. a
|
||||
`ZULIP_SITE` variable in a zuliprc file or the environment), but this
|
||||
is not yet documented for some of the integrations (the included
|
||||
integration documentation on `/integrations` will properly document
|
||||
how to do this for most integrations). We welcome pull requests for
|
||||
integrations that don't discuss this!
|
||||
|
||||
Similarly, you will need to instruct your users to specify the URL
|
||||
for your Zulip server when using the Zulip desktop and mobile apps.
|
||||
|
||||
### Memory leak mitigation
|
||||
|
||||
As a measure to mitigate the impact of potential memory leaks in one
|
||||
of the Zulip daemons, the service automatically restarts itself
|
||||
every Sunday early morning. See `/etc/cron.d/restart-zulip` for the
|
||||
precise configuration.
|
||||
|
||||
## Upgrading from a git repository
|
||||
|
||||
Zulip supports upgrading a production installation to any commit in
|
||||
Git, which is great for running pre-release versions or maintaining a
|
||||
small fork. If you're using Zulip 1.7 or newer, you can just run the
|
||||
command:
|
||||
|
||||
```
|
||||
# Upgrade to a tagged release
|
||||
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 1.8.1
|
||||
# Upgrade to a branch or other Git ref
|
||||
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git master
|
||||
```
|
||||
|
||||
and Zulip will automatically fetch the relevant Git commit and upgrade
|
||||
to that version of Zulip.
|
||||
|
||||
By default, this uses the main upstream Zulip server repository
|
||||
(example below), but you can configure any other Git repository by
|
||||
adding a section like this to `/etc/zulip/zulip.conf`:
|
||||
|
||||
```
|
||||
[deployment]
|
||||
git_repo_url = https://github.com/zulip/zulip.git
|
||||
```
|
||||
|
||||
See also our documentation on [modifying
|
||||
Zulip](../production/modifying-zulip.md) and [upgrading
|
||||
docker-zulip](https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository).
|
||||
|
||||
**Systems with limited RAM**: If you are running a minimal Zulip
|
||||
server with 2GB of RAM or less, the upgrade can fail due to the
|
||||
system running out of RAM running both the Zulip server and Zulip's
|
||||
static asset build process (`tools/webpack`
|
||||
is usually the step that fails). If you encounter this,
|
||||
you can run `supervisorctl stop all` to shut down the Zulip server
|
||||
while you run the upgrade (this will, of course, add some downtime,
|
||||
which is part of we already recommend more RAM for organizations of
|
||||
more than a few people).
|
||||
|
||||
### Upgrading using Git from Zulip 1.6 and older
|
||||
|
||||
If you're are upgrading from a Git repository, and you currently have
|
||||
Zulip 1.6 or older installed, you will need to install the
|
||||
dependencies for building Zulip's static assets. To do this, add
|
||||
`zulip::static_asset_compiler` to your `/etc/zulip/zulip.conf` file's
|
||||
`puppet_classes` entry, like this:
|
||||
|
||||
```
|
||||
puppet_classes = zulip::voyager, zulip::static_asset_compiler
|
||||
```
|
||||
|
||||
and run `scripts/zulip-puppet-apply`. After approving the changes,
|
||||
you'll be able to use `upgrade-zulip-from-git`.
|
||||
|
||||
After you've upgraded to Zulip 1.7 or above, you can safely remove
|
||||
`zulip::static_asset_compiler` from `puppet_classes`; in Zulip 1.7 and
|
||||
above, it is a dependency of `zulip::voyager` and thus these
|
||||
dependencies are installed by default.
|
||||
|
||||
## Upgrading the operating system
|
||||
|
||||
When you upgrade the operating system on which Zulip is installed
|
||||
(E.g. Ubuntu 14.04 Trusty to Ubuntu 16.04 Xenial), you need to take
|
||||
some additional steps to update your Zulip installation, documented
|
||||
below.
|
||||
|
||||
The steps are largely the same for the various OS upgrades aside from
|
||||
the versions of postgres, so you should be able to adapt these
|
||||
instructions for other supported platforms.
|
||||
|
||||
### Upgrading from Ubuntu 14.04 Trusty to 16.04 Xenial
|
||||
|
||||
1. First, as the Zulip user, stop the Zulip server and run the following
|
||||
to back up the system:
|
||||
|
||||
```
|
||||
supervisorctl stop all
|
||||
/home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
|
||||
```
|
||||
|
||||
2. Switch to the root user and upgrade the operating system using the
|
||||
OS's standard tooling. E.g. for Ubuntu, this means running
|
||||
`do-release-upgrade` and following the prompts until it completes
|
||||
successfully:
|
||||
|
||||
```
|
||||
sudo -i # Or otherwise get a root shell
|
||||
do-release-upgrade
|
||||
```
|
||||
|
||||
When `do-release-upgrade` asks you how to upgrade configuration
|
||||
files for services that Zulip manages like `redis`, `postgres`,
|
||||
`nginx`, and `memcached`, the best choice is `N` to keep the
|
||||
currently installed version. But it's not important; the next
|
||||
step will re-install Zulip's configuration in any case.
|
||||
|
||||
3. As root, upgrade the database installation and OS configuration to
|
||||
match the new OS version:
|
||||
|
||||
```
|
||||
apt remove upstart -y
|
||||
/home/zulip/deployments/current/scripts/zulip-puppet-apply -f
|
||||
pg_dropcluster 9.5 main --stop
|
||||
systemctl stop postgresql
|
||||
pg_upgradecluster -m upgrade 9.3 main
|
||||
pg_dropcluster 9.3 main
|
||||
apt remove postgresql-9.3
|
||||
systemctl start postgresql
|
||||
service memcached restart
|
||||
```
|
||||
|
||||
4. At this point, you are now running the version of postgres that
|
||||
comes with the new Ubuntu version. Finally, we need to reinstall the
|
||||
current version of Zulip, which among other things will recompile
|
||||
Zulip's Python module dependencies for your new version of Python:
|
||||
|
||||
```
|
||||
rm -rf /srv/zulip-venv-cache/*
|
||||
/home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
|
||||
/home/zulip/deployments/current/ --ignore-static-assets
|
||||
```
|
||||
|
||||
That last command will finish by restarting your Zulip server; you
|
||||
should now be able to navigate to its URL and confirm everything is
|
||||
working correctly.
|
||||
|
||||
### Upgrading from Ubuntu 16.04 Xenial to 18.04 Bionic
|
||||
|
||||
1. First, as the Zulip user, stop the Zulip server and run the following
|
||||
to back up the system:
|
||||
|
||||
```
|
||||
supervisorctl stop all
|
||||
/home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
|
||||
```
|
||||
|
||||
2. Switch to the root user and upgrade the operating system using the
|
||||
OS's standard tooling. E.g. for Ubuntu, this means running
|
||||
`do-release-upgrade` and following the prompts until it completes
|
||||
successfully:
|
||||
|
||||
```
|
||||
sudo -i # Or otherwise get a root shell
|
||||
do-release-upgrade
|
||||
```
|
||||
|
||||
When `do-release-upgrade` asks you how to upgrade configuration
|
||||
files for services that Zulip manages like `redis`, `postgres`,
|
||||
`nginx`, and `memcached`, the best choice is `N` to keep the
|
||||
currently installed version. But it's not important; the next
|
||||
step will re-install Zulip's configuration in any case.
|
||||
|
||||
3. As root, upgrade the database installation and OS configuration to
|
||||
match the new OS version:
|
||||
|
||||
```
|
||||
touch /usr/share/postgresql/10/pgroonga_setup.sql.applied
|
||||
/home/zulip/deployments/current/scripts/zulip-puppet-apply -f
|
||||
pg_dropcluster 10 main --stop
|
||||
systemctl stop postgresql
|
||||
pg_upgradecluster 9.5 main
|
||||
pg_dropcluster 9.5 main
|
||||
apt remove postgresql-9.5
|
||||
systemctl start postgresql
|
||||
systemctl restart memcached
|
||||
```
|
||||
|
||||
4. At this point, you are now running the version of postgres that
|
||||
comes with the new Ubuntu version. Finally, we need to reinstall the
|
||||
current version of Zulip, which among other things will recompile
|
||||
Zulip's Python module dependencies for your new version of Python:
|
||||
|
||||
```
|
||||
rm -rf /srv/zulip-venv-cache/*
|
||||
/home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
|
||||
/home/zulip/deployments/current/ --ignore-static-assets
|
||||
```
|
||||
|
||||
That last command will finish by restarting your Zulip server; you
|
||||
should now be able to navigate to its URL and confirm everything is
|
||||
working correctly.
|
||||
- [Backups, export and import](../production/export-and-import.md)
|
||||
- [Upgrade or modify Zulip](../production/upgrade-or-modify.md)
|
||||
|
||||
## Monitoring
|
||||
|
||||
@@ -496,10 +141,54 @@ running Zulip with larger teams (especially >1000 users).
|
||||
Questions, concerns, and bug reports about this area of Zulip are very
|
||||
welcome! This is an area we are hoping to improve.
|
||||
|
||||
## Securing your Zulip server
|
||||
## Sections that have moved
|
||||
|
||||
Zulip's security model is discussed in
|
||||
[a separate document](../production/security-model.md).
|
||||
These were once subsections of this page, but have since moved to
|
||||
dedicated pages; we preserve them here to avoid breaking old links.
|
||||
|
||||
### Securing your Zulip server
|
||||
|
||||
Moved to [Security Model](../production/security-model.md).
|
||||
|
||||
### Upgrading
|
||||
|
||||
Moved to [Upgrading to a release](../production/upgrade-or-modify.html#upgrading-to-a-release).
|
||||
|
||||
### Upgrading from a Git repository
|
||||
|
||||
Moved to [Upgrading from a Git
|
||||
repository](../production/upgrade-or-modify.html#upgrading-from-a-git-repository).
|
||||
|
||||
### Upgrading the operating system
|
||||
|
||||
Moved to [Upgrading the operating
|
||||
system](../production/upgrade-or-modify.html#upgrading-the-operating-system).
|
||||
|
||||
## API and your Zulip URL
|
||||
|
||||
To use the Zulip API with your Zulip server, you will need to use the
|
||||
API endpoint of e.g. `https://zulip.example.com/api`. Our Python
|
||||
API example scripts support this via the
|
||||
`--site=https://zulip.example.com` argument. The API bindings
|
||||
support it via putting `site=https://zulip.example.com` in your
|
||||
.zuliprc.
|
||||
|
||||
Every Zulip integration supports this sort of argument (or e.g. a
|
||||
`ZULIP_SITE` variable in a zuliprc file or the environment), but this
|
||||
is not yet documented for some of the integrations (the included
|
||||
integration documentation on `/integrations` will properly document
|
||||
how to do this for most integrations). We welcome pull requests for
|
||||
integrations that don't discuss this!
|
||||
|
||||
Similarly, you will need to instruct your users to specify the URL
|
||||
for your Zulip server when using the Zulip desktop and mobile apps.
|
||||
|
||||
## Memory leak mitigation
|
||||
|
||||
As a measure to mitigate the impact of potential memory leaks in one
|
||||
of the Zulip daemons, the service automatically restarts itself
|
||||
every Sunday early morning. See `/etc/cron.d/restart-zulip` for the
|
||||
precise configuration.
|
||||
|
||||
## Management commands
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ follows:
|
||||
1. Uncomment the `PUSH_NOTIFICATION_BOUNCER_URL =
|
||||
'https://push.zulipchat.com'` line in your `/etc/zulip/settings.py`
|
||||
file (i.e. remove the `#` at the start of the line), and
|
||||
[restart your Zulip server](../production/maintain-secure-upgrade.html#updating-settings).
|
||||
[restart your Zulip server](../production/settings.html#making-changes).
|
||||
If you installed your Zulip server with a version older than 1.6,
|
||||
you'll need to add the line (it won't be there to uncomment).
|
||||
|
||||
|
||||
@@ -1,210 +0,0 @@
|
||||
# Modifying or patching Zulip
|
||||
|
||||
Zulip is 100% free and open source software, and you're welcome to
|
||||
modify it! This page explains how to make and maintain modifications
|
||||
in a safe and convenient fashion.
|
||||
|
||||
If you do modify Zulip and then report an issue you see in your
|
||||
modified version of Zulip, please be responsible about communicating
|
||||
that fact:
|
||||
|
||||
* Ideally, you'd reproduce the issue in an unmodified version (e.g. on
|
||||
[chat.zulip.org](../contributing/chat-zulip-org.md) or
|
||||
[zulipchat.com](https://zulipchat.com)).
|
||||
* Where that is difficult or you think it's very unlikely your changes
|
||||
are related to the issue, just mention your changes in the issue report.
|
||||
|
||||
## Making changes
|
||||
|
||||
One way to modify Zulip is to just edit files under
|
||||
`/home/zulip/deployments/current` and then restart the server. This
|
||||
can work OK for testing small changes to Python code or shell scripts.
|
||||
But we don't recommend this approach for maintaining changes because:
|
||||
|
||||
* You cannot modify JavaScript, CSS, or other frontend files this way,
|
||||
because we don't include them in editable form in our production
|
||||
release tarballs (doing so would make our release tarballs much
|
||||
larger without any runtime benefit).
|
||||
* You will need to redo your changes after you next upgrade your Zulip
|
||||
server (or they will be lost).
|
||||
* You need to remember to restart the server or your changes won't
|
||||
have effect.
|
||||
* Your changes aren't tracked, so mistakes can be hard to debug.
|
||||
|
||||
Instead, we recommend the following GitHub-based workflow (see [our
|
||||
Git guide][git-guide] if you need a primer):
|
||||
|
||||
* Decide where you're going to edit Zulip's code. We recommend [using
|
||||
the Zulip development environment](../development/overview.md) on
|
||||
a desktop or laptop as it will make it extremely convenient for you
|
||||
to test your changes without deploying them in production. But if
|
||||
your changes are small or you're OK with risking downtime, you don't
|
||||
strictly need it; you just need an environment with Git installed.
|
||||
* **Important**. Determine what Zulip version you're running on your
|
||||
server. You can check by inspecting `ZULIP_VERSION` in
|
||||
`/home/zulip/deployments/current/version.py` (we'll use `2.0.4`
|
||||
below). If you apply your changes to the wrong version of Zulip,
|
||||
it's likely to fail and potentially cause downtime.
|
||||
* [Fork and clone][fork-clone] the [zulip/zulip][] repository on
|
||||
[GitHub](https://github.com).
|
||||
* Create a branch (named `acme-branch` below) containing your changes:
|
||||
|
||||
```
|
||||
cd zulip
|
||||
git checkout -b acme-branch 2.0.4
|
||||
```
|
||||
|
||||
* Use your favorite code editor to modify Zulip.
|
||||
* Commit your changes and push them to GitHub:
|
||||
|
||||
```
|
||||
git commit -a
|
||||
|
||||
# Use `git diff` to verify your changes are what you expect
|
||||
git diff 2.0.4 acme-branch
|
||||
|
||||
# Push the changes to your GitHub fork
|
||||
git push origin +acme-branch
|
||||
```
|
||||
|
||||
* Login to your Zulip server and configure and use
|
||||
[upgrade-zulip-from-git][] to install the changes; remember to
|
||||
configure `git_repo_url` to point to your fork on GitHub and run it as
|
||||
`upgrade-zulip-from-git acme-branch`.
|
||||
|
||||
This workflow solves all of the problems described above: your change
|
||||
will be compiled and installed correctly (restarting the server), and
|
||||
your changes will be tracked so that it's convenient to maintain them
|
||||
across future Zulip releases.
|
||||
|
||||
### Upgrading to future releases
|
||||
|
||||
Eventually, you'll want to upgrade to a new Zulip release
|
||||
(e.g. `2.1.0` in this example). If your changes were integrated into
|
||||
that Zulip release or are otherwise no longer needed, you can just use
|
||||
[upgrade-zulip][upgrade-zulip] as usual. Otherwise, you'll need to
|
||||
update your branch by rebasing your changes (starting from a
|
||||
[clone][fork-clone] of the [zulip/zulip][] repository):
|
||||
|
||||
```
|
||||
cd zulip
|
||||
git fetch --tags upstream
|
||||
git checkout acme-branch
|
||||
git rebase 2.1.0
|
||||
# Fix any errors or merge conflicts; see Zulip's Git Guide for advice
|
||||
|
||||
# Use `git diff` to verify your changes are what you expect
|
||||
git diff 2.1.0 acme-branch
|
||||
|
||||
git push origin +acme-branch
|
||||
```
|
||||
|
||||
And then use [upgrade-zulip-from-git][] to install your updated
|
||||
branch, as before.
|
||||
|
||||
### Making changes with docker-zulip
|
||||
|
||||
If you are using [docker-zulip][], there are two things that are
|
||||
different from the above:
|
||||
|
||||
* Because of how container images work, editing files directly is even
|
||||
more precarious, because Docker is designed for working with
|
||||
container images and may lose your changes.
|
||||
* Instead of running `upgrade-zulip-from-git`, you will need to use
|
||||
the [docker upgrade workflow][docker-zulip-upgrade] to build a
|
||||
container image based on your modified version of Zulip.
|
||||
|
||||
[docker-zulip]: https://github.com/zulip/docker-zulip
|
||||
[docker-zulip-upgrade]: https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository
|
||||
|
||||
## Applying changes from master
|
||||
|
||||
If you are experiencing an issue that has already been fixed by the
|
||||
Zulip development community, and you'd like to get the fix now, you
|
||||
have a few options. There are two possible ways you might get those
|
||||
fixes on your local Zulip server without waiting for an official release.
|
||||
|
||||
### Applying a small change
|
||||
|
||||
Many bugs have small/simple fixes. In this case, you can use the Git
|
||||
workflow [described above](#making-changes), using:
|
||||
|
||||
```
|
||||
git fetch upstream
|
||||
git cherry-pick abcd1234
|
||||
```
|
||||
|
||||
instead of "making changes locally" (where `abcd1234` is the commit ID
|
||||
of the change you'd like).
|
||||
|
||||
In general, we can't provide community support for issues caused by
|
||||
cherry-picking changes in this way. There is a major exception to
|
||||
this rule.
|
||||
|
||||
Zulip can be deployed in a wide variety of configurations and
|
||||
environments, and so we often merge fixes to bugs that we can
|
||||
reproduce in an automated test but have not directly reproduced in a
|
||||
production system. In these cases, we'll ask the user(s) who reported
|
||||
the bug to apply the patch to their production system to verify the
|
||||
fix works for them.
|
||||
|
||||
Generally, we'll only request this if we expect the fix in question to
|
||||
apply cleanly to the latest release without introducing regressions,
|
||||
and you can expect the Zulip community to be responsive in debugging
|
||||
any problems any caused by the patch.
|
||||
|
||||
### Upgrading to master
|
||||
|
||||
It's unsafe to backport arbitrary patches from master to an older
|
||||
version. Common issues include:
|
||||
|
||||
* Changes containing database migrations (new files under
|
||||
`zerver/migrations/`), which includes most new major features. We
|
||||
don't support applying database migrations out of order.
|
||||
* Changes that are stacked on top of other changes to the same system.
|
||||
* Essentially any patch with hundreds of lines of changes.
|
||||
|
||||
While it's possible to backport these sorts of changes, you're
|
||||
unlikely to succeed without help from the core team via a support
|
||||
contract.
|
||||
|
||||
If you need an unreleased feature, the right path is usually to Zulip
|
||||
master using [upgrade-zulip-from-git][]. Before upgrading to master,
|
||||
make sure you understand:
|
||||
|
||||
* The `master` branch is under very active development; dozens of new
|
||||
changes are integrated into it on most days. Master can have
|
||||
thousands of changes not present in the latest release (all of which
|
||||
will be included in our next release). There are probably some
|
||||
bugs.
|
||||
* That said we deploy master to chat.zulip.org and zulipchat.com on a
|
||||
regular basis (often daily), so it's very important to the project
|
||||
that it be stable. Most regressions will be minor UX issues or be
|
||||
fixed quickly.
|
||||
* The development community is very interested in helping debug issues
|
||||
that arise when upgrading from the latest release to master, since
|
||||
they provide us an opportunity to fix that category of issue before
|
||||
our next major release. (Much more so than we are in helping folks
|
||||
debug other custom changes). That said, we cannot make any
|
||||
guarantees about how quickly we'll resolve an issue to folks without
|
||||
a formal support contract.
|
||||
* We do not support downgrading from master to earlier versions, so if downtime
|
||||
for your Zulip server is unacceptable, make sure you have a current
|
||||
backup in case the upgrade fails.
|
||||
* Our changelog contains [draft release
|
||||
notes](../overview/changelog.md) available listing major changes
|
||||
since the last release. The **Upgrade notes** section will always
|
||||
be current, even if some new features aren't documented.
|
||||
|
||||
## Contributing patches
|
||||
|
||||
Zulip contains thousands of changes submitted by volunteer
|
||||
contributors like you. If your changes are likely to be of useful to
|
||||
other organizations, consider [contributing
|
||||
them](../overview/contributing.md).
|
||||
|
||||
[fork-clone]: ../git/cloning.html#get-zulip-code
|
||||
[upgrade-zulip-from-git]: ../production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip]: ../production/maintain-secure-upgrade.html#upgrading
|
||||
[git-guide]: ../git/index.md
|
||||
[zulip/zulip]: https://github.com/zulip/zulip/
|
||||
@@ -116,5 +116,5 @@ request; we love even small contributions, and we'd love to make the
|
||||
Zulip documentation cover everything anyone might want to know about
|
||||
running Zulip in production.
|
||||
|
||||
Next: [Maintaining and upgrading Zulip in
|
||||
production](../production/maintain-secure-upgrade.md).
|
||||
Next: [Maintaining](../production/maintain-secure-upgrade.md) and
|
||||
[upgrading](../production/upgrade-or-modify.md) Zulip in production.
|
||||
|
||||
574
docs/production/upgrade-or-modify.md
Normal file
574
docs/production/upgrade-or-modify.md
Normal file
@@ -0,0 +1,574 @@
|
||||
# Upgrade or modify Zulip
|
||||
|
||||
This page explains how to upgrade, patch, or modify Zulip, including:
|
||||
|
||||
- [Upgrading to a release](#upgrading-to-a-release)
|
||||
- [Upgrading from a git repository](#upgrading-from-a-git-repository)
|
||||
- [Troubleshooting and rollback](#troubleshooting-and-rollback)
|
||||
- [Preserving local changes to configuration files](#preserving-local-changes-to-configuration-files)
|
||||
- [Upgrading the operating system](#upgrading-the-operating-system)
|
||||
- [Modifying Zulip](#modifying-zulip)
|
||||
- [Applying changes from master](#applying-changes-from-master)
|
||||
|
||||
## Upgrading to a release
|
||||
|
||||
Note that there are additional instructions if you're [using
|
||||
docker-zulip][docker-upgrade], have [patched Zulip](#modifying-zulip),
|
||||
or have [modified Zulip-managed configuration
|
||||
files](#preserving-local-changes-to-configuration-files). To upgrade
|
||||
to a new Zulip release:
|
||||
|
||||
1. Download the appropriate release tarball from
|
||||
<https://www.zulip.org/dist/releases/> You can download the latest
|
||||
release with:
|
||||
|
||||
```
|
||||
wget https://www.zulip.org/dist/releases/zulip-server-latest.tar.gz
|
||||
```
|
||||
|
||||
You also have the option of upgrading Zulip [to a version in a Git
|
||||
repository directly](#upgrading-from-a-git-repository) or creating
|
||||
your own release tarballs from a copy of the [zulip.git
|
||||
repository](https://github.com/zulip/zulip) using
|
||||
`tools/build-release-tarball`.
|
||||
|
||||
1. Login to your Zulip and run as root:
|
||||
|
||||
```
|
||||
/home/zulip/deployments/current/scripts/upgrade-zulip zulip-server-VERSION.tar.gz
|
||||
```
|
||||
|
||||
The upgrade process will:
|
||||
* Shut down the Zulip service
|
||||
* Run `apt-get upgrade`
|
||||
* Run a `puppet apply`
|
||||
* Run any database migrations
|
||||
* Bring the Zulip service back up on the new version.
|
||||
|
||||
Upgrading will result in brief downtime for the service, which should
|
||||
be under 30 seconds unless there is an expensive database migration
|
||||
involved (these will be documented in the [release
|
||||
notes](../overview/changelog.md), and usually can be avoided with
|
||||
some care). If downtime is problematic for your organization,
|
||||
consider testing the upgrade on a
|
||||
[backup](../production/export-and-import.html#backups) in advance,
|
||||
doing the final upgrade at off hours, or buying a support contract.
|
||||
|
||||
See the [troubleshooting guide](#troubleshooting-and-rollback) if you
|
||||
run into any issues or need to roll back the upgrade.
|
||||
|
||||
## Upgrading from a git repository
|
||||
|
||||
Zulip supports upgrading a production installation to any commit in a
|
||||
Git repository, which is great for [running pre-release changes from
|
||||
master](#applying-changes-from-master) or [maintaining a
|
||||
fork](#making-changes). The process is simple:
|
||||
|
||||
```
|
||||
# Upgrade to an official release
|
||||
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 1.8.1
|
||||
# Upgrade to a branch or other Git ref
|
||||
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git master
|
||||
```
|
||||
|
||||
Zulip will automatically fetch the relevant Git commit and upgrade to
|
||||
that version of Zulip. Note that [downgrading to an older
|
||||
version](#upgrading-to-master) using this process won't work.
|
||||
|
||||
By default, this uses the main upstream Zulip server repository, but
|
||||
you can configure any other Git repository by adding a section like
|
||||
this to `/etc/zulip/zulip.conf`:
|
||||
|
||||
```
|
||||
[deployment]
|
||||
git_repo_url = https://github.com/zulip/zulip.git
|
||||
```
|
||||
|
||||
See also our documentation on [upgrading
|
||||
docker-zulip](https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository).
|
||||
|
||||
## Troubleshooting and rollback
|
||||
|
||||
See also the general Zulip server [troubleshooting
|
||||
guide](../production/troubleshooting.md).
|
||||
|
||||
The upgrade scripts are idempotent, so there's no harm in trying again
|
||||
after resolving an issue. The most common causes of errors are:
|
||||
|
||||
* Networking issues (e.g. your Zulip server doesn't have reliable
|
||||
Internet access or needs a proxy setup). Fix the networking issue
|
||||
and try again.
|
||||
* Especially when using `upgrade-zulip-from-git`, systems with the
|
||||
minimal RAM for running Zulip can run into out-of-memory issues
|
||||
during the upgrade process (generally `tools/webpack` is the step
|
||||
that fails). You can get past this by shutting down the Zulip
|
||||
server with `supervisorctl stop all` to free up RAM before running
|
||||
the upgrade process.
|
||||
|
||||
Useful logs are available in a few places:
|
||||
* The Zulip upgrade scripts log all output to
|
||||
`/var/log/zulip/upgrade.log`.
|
||||
* The Zulip server logs all Internal Server Errors to
|
||||
`/var/log/zulip/errors.log`.
|
||||
|
||||
If you need help and don't have a support contract, you can visit
|
||||
[#production
|
||||
help](https://chat.zulip.org/#narrow/stream/31-production-help) in the
|
||||
[Zulip development community
|
||||
server](../contributing/chat-zulip-org.md) for best-effort help.
|
||||
Please include the relevant error output from the above logs in a
|
||||
[markdown code
|
||||
block](https://zulipchat.com/help/format-your-message-using-markdown#code)
|
||||
in any reports.
|
||||
|
||||
### Rolling back to a prior version
|
||||
|
||||
This rollback process is primarily useful for minor releases
|
||||
(e.g. `2.0.3` to `2.0.6`); a more complicated process is required to
|
||||
rollback database migrations before downgrading to an older major
|
||||
release.
|
||||
|
||||
The Zulip upgrade process works by creating a new deployment under
|
||||
`/home/zulip/deployments/` containing a complete copy of the Zulip server code,
|
||||
and then moving the symlinks at `/home/zulip/deployments/{current,last,next}`
|
||||
as part of the upgrade process.
|
||||
|
||||
This means that if the new version isn't working,
|
||||
you can quickly downgrade to the old version by running
|
||||
`/home/zulip/deployments/last/scripts/restart-server`, or to an
|
||||
earlier previous version by running
|
||||
`/home/zulip/deployments/DATE/scripts/restart-server`. The
|
||||
`restart-server` script stops any running Zulip server, and starts
|
||||
the version corresponding to the `restart-server` path you call.
|
||||
|
||||
## Preserving local changes to configuration files
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
If you have modified configuration files installed by
|
||||
Zulip (e.g. the nginx configuration), the Zulip upgrade process will
|
||||
overwrite your configuration when it does the `puppet apply`.
|
||||
```
|
||||
|
||||
You can test whether this will happen assuming no upstream changes to
|
||||
the configuration using `scripts/zulip-puppet-apply` (without the
|
||||
`-f` option), which will do a test puppet run and output and changes
|
||||
it would make. Using this list, you can save a copy of any files
|
||||
that you've modified, do the upgrade, and then restore your
|
||||
configuration.
|
||||
|
||||
That said, Zulip's configuration files are designed to be flexible
|
||||
enough for a wide range of installations, from a small self-hosted
|
||||
system to Zulip Cloud. Before making local changes to a configuration
|
||||
file, first check whether there's an option supported by
|
||||
`/etc/zulip/zulip.conf` for the customization you need. And if you
|
||||
need to make local modifications, please report the issue so that we
|
||||
can make the Zulip puppet configuration flexible enough to handle your
|
||||
setup.
|
||||
|
||||
### nginx configuration changes
|
||||
|
||||
If you need to modify Zulip's `nginx` configuration, we recommend
|
||||
first attempting to add configuration to `/etc/nginx/conf.d` or
|
||||
`/etc/nginx/zulip-include/app.d`; those directories are designed for
|
||||
custom configuration.
|
||||
|
||||
## Upgrading the operating system
|
||||
|
||||
When you upgrade the operating system on which Zulip is installed
|
||||
(E.g. Ubuntu 14.04 Trusty to Ubuntu 16.04 Xenial), you need to take
|
||||
some additional steps to update your Zulip installation, documented
|
||||
below.
|
||||
|
||||
The steps are largely the same for the various OS upgrades aside from
|
||||
the versions of postgres, so you should be able to adapt these
|
||||
instructions for other supported platforms.
|
||||
|
||||
### Upgrading from Ubuntu 14.04 Trusty to 16.04 Xenial
|
||||
|
||||
1. First, as the Zulip user, stop the Zulip server and run the following
|
||||
to back up the system:
|
||||
|
||||
```
|
||||
supervisorctl stop all
|
||||
/home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
|
||||
```
|
||||
|
||||
2. Switch to the root user and upgrade the operating system using the
|
||||
OS's standard tooling. E.g. for Ubuntu, this means running
|
||||
`do-release-upgrade` and following the prompts until it completes
|
||||
successfully:
|
||||
|
||||
```
|
||||
sudo -i # Or otherwise get a root shell
|
||||
do-release-upgrade
|
||||
```
|
||||
|
||||
When `do-release-upgrade` asks you how to upgrade configuration
|
||||
files for services that Zulip manages like `redis`, `postgres`,
|
||||
`nginx`, and `memcached`, the best choice is `N` to keep the
|
||||
currently installed version. But it's not important; the next
|
||||
step will re-install Zulip's configuration in any case.
|
||||
|
||||
3. As root, upgrade the database installation and OS configuration to
|
||||
match the new OS version:
|
||||
|
||||
```
|
||||
apt remove upstart -y
|
||||
/home/zulip/deployments/current/scripts/zulip-puppet-apply -f
|
||||
pg_dropcluster 9.5 main --stop
|
||||
systemctl stop postgresql
|
||||
pg_upgradecluster -m upgrade 9.3 main
|
||||
pg_dropcluster 9.3 main
|
||||
apt remove postgresql-9.3
|
||||
systemctl start postgresql
|
||||
service memcached restart
|
||||
```
|
||||
|
||||
4. At this point, you are now running the version of postgres that
|
||||
comes with the new Ubuntu version. Finally, we need to reinstall the
|
||||
current version of Zulip, which among other things will recompile
|
||||
Zulip's Python module dependencies for your new version of Python:
|
||||
|
||||
```
|
||||
rm -rf /srv/zulip-venv-cache/*
|
||||
/home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
|
||||
/home/zulip/deployments/current/ --ignore-static-assets
|
||||
```
|
||||
|
||||
That last command will finish by restarting your Zulip server; you
|
||||
should now be able to navigate to its URL and confirm everything is
|
||||
working correctly.
|
||||
|
||||
### Upgrading from Ubuntu 16.04 Xenial to 18.04 Bionic
|
||||
|
||||
1. First, as the Zulip user, stop the Zulip server and run the following
|
||||
to back up the system:
|
||||
|
||||
```
|
||||
supervisorctl stop all
|
||||
/home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
|
||||
```
|
||||
|
||||
2. Switch to the root user and upgrade the operating system using the
|
||||
OS's standard tooling. E.g. for Ubuntu, this means running
|
||||
`do-release-upgrade` and following the prompts until it completes
|
||||
successfully:
|
||||
|
||||
```
|
||||
sudo -i # Or otherwise get a root shell
|
||||
do-release-upgrade
|
||||
```
|
||||
|
||||
When `do-release-upgrade` asks you how to upgrade configuration
|
||||
files for services that Zulip manages like `redis`, `postgres`,
|
||||
`nginx`, and `memcached`, the best choice is `N` to keep the
|
||||
currently installed version. But it's not important; the next
|
||||
step will re-install Zulip's configuration in any case.
|
||||
|
||||
3. As root, upgrade the database installation and OS configuration to
|
||||
match the new OS version:
|
||||
|
||||
```
|
||||
touch /usr/share/postgresql/10/pgroonga_setup.sql.applied
|
||||
/home/zulip/deployments/current/scripts/zulip-puppet-apply -f
|
||||
pg_dropcluster 10 main --stop
|
||||
systemctl stop postgresql
|
||||
pg_upgradecluster 9.5 main
|
||||
pg_dropcluster 9.5 main
|
||||
apt remove postgresql-9.5
|
||||
systemctl start postgresql
|
||||
systemctl restart memcached
|
||||
```
|
||||
|
||||
4. At this point, you are now running the version of postgres that
|
||||
comes with the new Ubuntu version. Finally, we need to reinstall the
|
||||
current version of Zulip, which among other things will recompile
|
||||
Zulip's Python module dependencies for your new version of Python:
|
||||
|
||||
```
|
||||
rm -rf /srv/zulip-venv-cache/*
|
||||
/home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
|
||||
/home/zulip/deployments/current/ --ignore-static-assets
|
||||
```
|
||||
|
||||
That last command will finish by restarting your Zulip server; you
|
||||
should now be able to navigate to its URL and confirm everything is
|
||||
working correctly.
|
||||
|
||||
|
||||
## Modifying Zulip
|
||||
|
||||
Zulip is 100% free and open source software, and you're welcome to
|
||||
modify it! This section explains how to make and maintain
|
||||
modifications in a safe and convenient fashion.
|
||||
|
||||
If you do modify Zulip and then report an issue you see in your
|
||||
modified version of Zulip, please be responsible about communicating
|
||||
that fact:
|
||||
|
||||
* Ideally, you'd reproduce the issue in an unmodified version (e.g. on
|
||||
[chat.zulip.org](../contributing/chat-zulip-org.md) or
|
||||
[zulipchat.com](https://zulipchat.com)).
|
||||
* Where that is difficult or you think it's very unlikely your changes
|
||||
are related to the issue, just mention your changes in the issue report.
|
||||
|
||||
If you're looking to modify Zulip by applying changes developed by the
|
||||
Zulip core team and merged into master, skip to [this
|
||||
section](#applying-changes-from-master).
|
||||
|
||||
## Making changes
|
||||
|
||||
One way to modify Zulip is to just edit files under
|
||||
`/home/zulip/deployments/current` and then restart the server. This
|
||||
can work OK for testing small changes to Python code or shell scripts.
|
||||
But we don't recommend this approach for maintaining changes because:
|
||||
|
||||
* You cannot modify JavaScript, CSS, or other frontend files this way,
|
||||
because we don't include them in editable form in our production
|
||||
release tarballs (doing so would make our release tarballs much
|
||||
larger without any runtime benefit).
|
||||
* You will need to redo your changes after you next upgrade your Zulip
|
||||
server (or they will be lost).
|
||||
* You need to remember to restart the server or your changes won't
|
||||
have effect.
|
||||
* Your changes aren't tracked, so mistakes can be hard to debug.
|
||||
|
||||
Instead, we recommend the following GitHub-based workflow (see [our
|
||||
Git guide][git-guide] if you need a primer):
|
||||
|
||||
* Decide where you're going to edit Zulip's code. We recommend [using
|
||||
the Zulip development environment](../development/overview.md) on
|
||||
a desktop or laptop as it will make it extremely convenient for you
|
||||
to test your changes without deploying them in production. But if
|
||||
your changes are small or you're OK with risking downtime, you don't
|
||||
strictly need it; you just need an environment with Git installed.
|
||||
* **Important**. Determine what Zulip version you're running on your
|
||||
server. You can check by inspecting `ZULIP_VERSION` in
|
||||
`/home/zulip/deployments/current/version.py` (we'll use `2.0.4`
|
||||
below). If you apply your changes to the wrong version of Zulip,
|
||||
it's likely to fail and potentially cause downtime.
|
||||
* [Fork and clone][fork-clone] the [zulip/zulip][] repository on
|
||||
[GitHub](https://github.com).
|
||||
* Create a branch (named `acme-branch` below) containing your changes:
|
||||
|
||||
```
|
||||
cd zulip
|
||||
git checkout -b acme-branch 2.0.4
|
||||
```
|
||||
|
||||
* Use your favorite code editor to modify Zulip.
|
||||
* Commit your changes and push them to GitHub:
|
||||
|
||||
```
|
||||
git commit -a
|
||||
|
||||
# Use `git diff` to verify your changes are what you expect
|
||||
git diff 2.0.4 acme-branch
|
||||
|
||||
# Push the changes to your GitHub fork
|
||||
git push origin +acme-branch
|
||||
```
|
||||
|
||||
* Login to your Zulip server and configure and use
|
||||
[upgrade-zulip-from-git][] to install the changes; remember to
|
||||
configure `git_repo_url` to point to your fork on GitHub and run it as
|
||||
`upgrade-zulip-from-git acme-branch`.
|
||||
|
||||
This workflow solves all of the problems described above: your change
|
||||
will be compiled and installed correctly (restarting the server), and
|
||||
your changes will be tracked so that it's convenient to maintain them
|
||||
across future Zulip releases.
|
||||
|
||||
### Upgrading to future releases
|
||||
|
||||
Eventually, you'll want to upgrade to a new Zulip release
|
||||
(e.g. `2.1.0` in this example). If your changes were integrated into
|
||||
that Zulip release or are otherwise no longer needed, you can just use
|
||||
[upgrade as usual](#upgrading-to-a-release). Otherwise, you'll need
|
||||
to update your branch by rebasing your changes (starting from a
|
||||
[clone][fork-clone] of the [zulip/zulip][] repository):
|
||||
|
||||
If you want to keep your modifications, you'll need to
|
||||
update your branch by rebasing your changes (starting from a
|
||||
[clone][fork-clone] of the [zulip/zulip][] repository):
|
||||
|
||||
```
|
||||
cd zulip
|
||||
git fetch --tags upstream
|
||||
git checkout acme-branch
|
||||
git rebase 2.1.0
|
||||
# Fix any errors or merge conflicts; see Zulip's Git Guide for advice
|
||||
|
||||
# Use `git diff` to verify your changes are what you expect
|
||||
git diff 2.1.0 acme-branch
|
||||
|
||||
git push origin +acme-branch
|
||||
```
|
||||
|
||||
And then use [upgrade-zulip-from-git][] to install your updated
|
||||
branch, as before.
|
||||
|
||||
### Making changes with docker-zulip
|
||||
|
||||
If you are using [docker-zulip][], there are two things that are
|
||||
different from the above:
|
||||
|
||||
* Because of how container images work, editing files directly is even
|
||||
more precarious, because Docker is designed for working with
|
||||
container images and may lose your changes.
|
||||
* Instead of running `upgrade-zulip-from-git`, you will need to use
|
||||
the [docker upgrade workflow][docker-zulip-upgrade] to build a
|
||||
container image based on your modified version of Zulip.
|
||||
|
||||
[docker-zulip]: https://github.com/zulip/docker-zulip
|
||||
[docker-zulip-upgrade]: https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository
|
||||
|
||||
## Applying changes from master
|
||||
|
||||
If you are experiencing an issue that has already been fixed by the
|
||||
Zulip development community, and you'd like to get the fix now, you
|
||||
have a few options. There are two possible ways you might get those
|
||||
fixes on your local Zulip server without waiting for an official release.
|
||||
|
||||
### Applying a small change
|
||||
|
||||
Many bugs have small/simple fixes. In this case, you can use the Git
|
||||
workflow [described above](#making-changes), using:
|
||||
|
||||
```
|
||||
git fetch upstream
|
||||
git cherry-pick abcd1234
|
||||
```
|
||||
|
||||
instead of "making changes locally" (where `abcd1234` is the commit ID
|
||||
of the change you'd like).
|
||||
|
||||
In general, we can't provide support for issues caused by
|
||||
cherry-picking arbitrary commits if the issues don't also affect
|
||||
master or an official release. However, there is a major exception to
|
||||
this rule.
|
||||
|
||||
Zulip can be deployed in a wide variety of configurations and
|
||||
environments, and so we often merge fixes to bugs that we can
|
||||
reproduce in an automated test but have not directly reproduced in a
|
||||
production system. In these cases, we'll ask the user(s) who reported
|
||||
the bug to apply the patch to their production system to verify the
|
||||
fix works for them.
|
||||
|
||||
Generally, we'll only request this if we expect the fix in question to
|
||||
apply cleanly to the latest release without introducing regressions,
|
||||
and you can expect the Zulip community to be responsive in debugging
|
||||
any problems any caused by a patch we asked you to apply.
|
||||
|
||||
### Upgrading to master
|
||||
|
||||
It's unsafe to backport arbitrary patches from master to an older
|
||||
version. Common issues include:
|
||||
|
||||
* Changes containing database migrations (new files under
|
||||
`zerver/migrations/`), which includes most new features. We
|
||||
don't support applying database migrations out of order.
|
||||
* Changes that are stacked on top of other changes to the same system.
|
||||
* Essentially any patch with hundreds of lines of changes.
|
||||
|
||||
While it's possible to backport these sorts of changes, you're
|
||||
unlikely to succeed without help from the core team via a support
|
||||
contract.
|
||||
|
||||
If you need an unreleased feature, the best path is usually to Zulip
|
||||
master using [upgrade-zulip-from-git][]. Before upgrading to master,
|
||||
make sure you understand:
|
||||
|
||||
* The `master` branch is under very active development; dozens of new
|
||||
changes are integrated into it on most days. Master can have
|
||||
thousands of changes not present in the latest release (all of which
|
||||
will be included in our next release). There are probably some
|
||||
bugs.
|
||||
* That said we deploy master to chat.zulip.org and zulipchat.com on a
|
||||
regular basis (often daily), so it's very important to the project
|
||||
that it be stable. Most regressions will be minor UX issues or be
|
||||
fixed quickly.
|
||||
* The development community is very interested in helping debug issues
|
||||
that arise when upgrading from the latest release to master, since
|
||||
they provide us an opportunity to fix that category of issue before
|
||||
our next major release. (Much more so than we are in helping folks
|
||||
debug other custom changes). That said, we cannot make any
|
||||
guarantees about how quickly we'll resolve an issue to folks without
|
||||
a formal support contract.
|
||||
* We do not support downgrading from master to earlier versions, so if downtime
|
||||
for your Zulip server is unacceptable, make sure you have a current
|
||||
backup in case the upgrade fails.
|
||||
* Our changelog contains [draft release
|
||||
notes](../overview/changelog.md) available listing major changes
|
||||
since the last release. The **Upgrade notes** section will always
|
||||
be current, even if some new features aren't documented.
|
||||
|
||||
### Applying system updates
|
||||
|
||||
The Zulip upgrade script will automatically run `apt-get update` and
|
||||
then `apt-get upgrade`, to make sure you have any new versions of
|
||||
dependencies (this will also update system packages). We assume that
|
||||
you will install security updates from `apt` regularly, according to
|
||||
your usual security practices for a production server.
|
||||
|
||||
If you'd like to minimize downtime when installing a Zulip server
|
||||
upgrade, you may want to do an `apt-get upgrade` (and then restart the
|
||||
server and check everything is working) before running the Zulip
|
||||
upgrade script.
|
||||
|
||||
There's one `apt` package to be careful about: upgrading `postgresql`
|
||||
while the server is running may result in an outage (basically,
|
||||
`postgresql` might stop accepting new queries but refuse to shut down
|
||||
while waiting for connections from the Zulip server to shut down).
|
||||
While this only happens sometimes, it can be hard to fix for someone
|
||||
who isn't comfortable managing a `postgresql` database [1]. You can
|
||||
avoid that possibility with the following procedure (run as root):
|
||||
|
||||
```
|
||||
apt-get update
|
||||
supervisorctl stop all
|
||||
apt-get upgrade -y
|
||||
supervisorctl start all
|
||||
```
|
||||
|
||||
[1] If this happens to you, just stop the Zulip server, restart
|
||||
postgres, and then start the Zulip server again, and you'll be back in
|
||||
business.
|
||||
|
||||
#### Disabling unattended upgrades
|
||||
|
||||
**Important**: We recommend that you
|
||||
[disable Ubuntu's unattended-upgrades][disable-unattended-upgrades],
|
||||
and instead install apt upgrades manually. With unattended upgrades
|
||||
enabled, the moment a new Postgres release is published, your Zulip
|
||||
server will have its postgres server upgraded (and thus restarted).
|
||||
|
||||
When one of the services Zulip depends on (postgres, memcached, redis,
|
||||
rabbitmq) is restarted, that services will disconnect everything using
|
||||
them (like the Zulip server), and every operation that Zulip does
|
||||
which uses that service will throw an exception (and send you an error
|
||||
report email). These apparently "random errors" can be confusing and
|
||||
might cause you to worry incorrectly about the stability of the Zulip
|
||||
software, which in fact the problem is that Ubuntu automatically
|
||||
upgraded and then restarted key Zulip dependencies.
|
||||
|
||||
Instead, we recommend installing updates for these services manually,
|
||||
and then restarting the Zulip server with
|
||||
`/home/zulip/deployments/current/scripts/restart-server` afterwards.
|
||||
|
||||
[disable-unattended-upgrades]: https://linoxide.com/ubuntu-how-to/enable-disable-unattended-upgrades-ubuntu-16-04/
|
||||
|
||||
## Contributing patches
|
||||
|
||||
Zulip contains thousands of changes submitted by volunteer
|
||||
contributors like you. If your changes are likely to be of useful to
|
||||
other organizations, consider [contributing
|
||||
them](../overview/contributing.md).
|
||||
|
||||
[fork-clone]: ../git/cloning.html#get-zulip-code
|
||||
[upgrade-zulip-from-git]: #upgrading-from-a-git-repository
|
||||
[upgrade-zulip]: #upgrading
|
||||
[git-guide]: ../git/index.md
|
||||
[zulip/zulip]: https://github.com/zulip/zulip/
|
||||
[docker-upgrade]: https://github.com/zulip/docker-zulip#upgrading-the-zulip-container
|
||||
@@ -97,4 +97,4 @@ to mark the appropriate users as administrators.
|
||||
[issue mentions](https://gitter.zendesk.com/hc/en-us/articles/200176692-Issue-and-Pull-Request-mentions)
|
||||
aren't translated into anything yet.
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
|
||||
@@ -130,7 +130,7 @@ root domain. Replace the last line above with the following, after replacing
|
||||
|
||||
{!import-login.md!}
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
|
||||
## Caveats
|
||||
|
||||
@@ -152,5 +152,5 @@ rooms. You can pick one of the following options for handling this:
|
||||
access token via `--token=abcd1234` in `manage.py convert_hipchat_data`
|
||||
(or include it in your request, if importing into Zulip Cloud).
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
[hipchat-api-tokens]: https://developer.atlassian.com/server/hipchat/hipchat-rest-api-access-tokens/
|
||||
|
||||
@@ -170,7 +170,7 @@ root domain. Replace the last line above with the following, after replacing
|
||||
|
||||
{!import-login.md!}
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
|
||||
## Caveats
|
||||
|
||||
@@ -188,4 +188,4 @@ messages with a specific Mattermost team. For that reason, the import
|
||||
tool will only import private messages for data export archives
|
||||
containing a single Mattermost team.
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
|
||||
@@ -97,4 +97,4 @@ root domain. Replace the last line above with the following, after replacing
|
||||
|
||||
- The "joined #channel_name" messages are not imported.
|
||||
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
|
||||
[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
|
||||
|
||||
Reference in New Issue
Block a user