paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-02 04:53:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Improve Upgrade Zulip documentation.

Browse Source 
- Arrange info more cleanly into sections.
- Avoid duplicating git versions documentation.
This commit is contained in:
Alya Abbott
2025-02-28 22:03:01 -08:00
committed by Tim Abbott
parent a33d7bacb9
commit 8e810aae54
1 changed files with 158 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

295
docs/production/upgrade.md
View File

@@ -7,92 +7,128 @@ This page explains how to upgrade a Zulip server, including:
- [Updating `settings.py` inline documentation](#updating-settingspy-inline-documentation)
- [Troubleshooting and rollback](#troubleshooting-and-rollback)
- [Preserving local changes to service configuration files](#preserving-local-changes-to-service-configuration-files)
- [Upgrading the operating system](#upgrading-the-operating-system)
- [Upgrading PostgreSQL](#upgrading-postgresql)
- [Upgrading the operating system](#upgrading-the-operating-system)
If you have an questions or problems with your upgrade process, best-effort
community support is available in the [Zulip development
community](https://zulip.com/development-community/).
:::{note}
For professional support, upgrade to [Zulip
Business](https://zulip.com/plans/#self-hosted), or reach out to
[sales@zulip.com](mailto:sales@zulip.com).
:::
## Upgrading to a release
Note that there are additional instructions if you're [using
docker-zulip][docker-upgrade], have [patched Zulip](modify.md),
or have [modified Zulip-managed configuration
files](#preserving-local-changes-to-service-configuration-files). To upgrade
to a new Zulip release:
:::{important}
1. Read the [upgrade notes](../overview/changelog.md#upgrade-notes)
for all releases newer than what is currently installed.
Be sure to follow the additional instructions if you're [using
docker-zulip][docker-upgrade], have [patched Zulip](modify.md), or have
[modified Zulip-managed configuration
files](#preserving-local-changes-to-service-configuration-files).
1. Download the appropriate release tarball from
<https://download.zulip.com/server/>. You can get the latest
release (**Zulip Server {{ LATEST_RELEASE_VERSION }}**) with the
following command:
:::
To upgrade to a new Zulip release:
1. Read the [upgrade notes](../overview/changelog.md#upgrade-notes) for all
releases between your current release and the one you're upgrading to.
1. [Download](https://download.zulip.com/server/) the appropriate release
tarball. You can get the latest release (**Zulip Server
{{ LATEST_RELEASE_VERSION }}**) with the following command:
```bash
curl -fLO https://download.zulip.com/server/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. Log in to your Zulip and run as root:
1. Log in to your Zulip, and run as root:
```bash
/home/zulip/deployments/current/scripts/upgrade-zulip zulip-server-latest.tar.gz
```
The upgrade process will:
Once the Zulip upgrade is complete, you may also wish to [upgrade the version of
PostgreSQL](#upgrading-postgresql).
- Run `apt-get upgrade`
- Install new versions of Zulip's dependencies (mainly Python packages).
- (`upgrade-zulip-from-git` only) Build Zulip's frontend assets using `webpack`.
- Shut down the Zulip service
- Run a `puppet apply`
- Run any database migrations
- Bring the Zulip service back up on the new version.
### What to expect during an upgrade
The upgrade process will:
1. Run `apt-get upgrade`.
1. Install new versions of Zulip's dependencies (mainly Python packages).
1. Shut down the Zulip service.
1. Run a `puppet apply`.
1. Run any database migrations.
1. 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,
involved. Such migrations will be documented in the [release
notes](../overview/changelog.md), and can usually can be avoided with
some care. If downtime is problematic for your organization,
consider testing the upgrade on a
[backup](export-and-import.md#backups) in advance,
doing the final upgrade at off hours, or buying a support contract.
doing the final upgrade at off hours, or arranging support.
See the [troubleshooting guide](#troubleshooting-and-rollback) if you
run into any issues or need to roll back the upgrade.
:::{note}
After you have completed the Zulip upgrade, you may also wish to [upgrade the
version of PostgreSQL](#upgrading-postgresql).
If you run into any issues or need to roll back the upgrade, see the
[troubleshooting guide](#troubleshooting-and-rollback).
:::
## 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
`main`](modify.md#applying-changes-from-main) or [maintaining a
fork](modify.md#making-changes). The process is simple:
:::{important}
If you are upgrading docker-zulip, please follow [these
instructions](https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository).
:::
Zulip supports upgrading a production installation to any commit in a Git
repository. This lets you get unreleased features and bugfixes, or [maintain a
fork](modify.md#making-changes) of Zulip.
### Upgrading to an unreleased version of Zulip
The [git versions](../overview/release-lifecycle.md#git-versions) documentation
describes some branches you may choose to upgrade to, depending on your
requirements.
If you are considering upgrading to `main`, see our [upgrading to `main`
guide](modify.md#upgrading-to-main) for detailed information. You can also
[apply a small change](modify.md#applying-changes-from-main) to get a fix for an
issue that matters for your organization.
To upgrade to a branch from Git, simply run:
```bash
# Upgrade to an official release
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 9.4
# Upgrade to a branch (or other Git ref)
# Upgrade to a maintenance branch
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 9.x
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git main
# Upgrade to the Zulip Cloud branch
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git zulip-cloud-current
# Upgrade to the `main` branch
/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 9.4
```
Zulip will automatically fetch the relevant Git commit and upgrade to
that version of Zulip.
Branches with names like `9.x` are stable release branches,
containing the changes planned for the next minor release
(e.g., 9.4); we support these stable release branches as though they
were a published release.
In addition to the steps described [above](#what-to-expect-during-an-upgrade),
the upgrade process will also build Zulip's frontend assets using `webpack`.
The `main` branch contains changes planned for the next major
release (e.g., 10.0); see our documentation on [running
`main`](modify.md#upgrading-to-main) before upgrading to it.
#### Upgrading from another repository
By default, this uses the main upstream Zulip server repository, but
you can configure any other Git repository by adding a section like
@@ -103,17 +139,14 @@ this to `/etc/zulip/zulip.conf`:
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).
## Updating `settings.py` inline documentation
Zulip installations often upgrade many times over their lifetime, and
we strive to keep all configuration files backwards-compatible.
However, our practice of leaving the `/etc/zulip/settings.py`
unchanged during upgrades means that there may be new features which
are not documented in that file, since it was based on a template
provided by an earlier version of Zulip, during the initial install.
Zulip installations often upgrade many times over their lifetime, and we strive
to keep all configuration files backwards-compatible. The
`/etc/zulip/settings.py` file is not automatically modified during upgrades.
After an upgrade, new features may thus be missing from that file, as it is
based on a template provided by an earlier version of Zulip.
After upgrading across major versions of Zulip Server, we recommend
comparing your `/etc/zulip/settings.py` file to the current settings
@@ -136,9 +169,9 @@ suggest using that updated template to update
section in `/etc/zulip/settings-new.py` and copy the setting from
`settings.py` into there.
The following tool may help, by finding the most likely version of
the template that your `/etc/zulip/settings.py` was installed
using, and the differences that your file has from that:
To help with this process, the following tool finds the most likely version
of the template that your `/etc/zulip/settings.py` was installed from, and
shows the modifications you've made:
```bash
/home/zulip/deployments/current/scripts/setup/compare-settings-to-template
@@ -162,9 +195,6 @@ suggest using that updated template to update
## Troubleshooting and rollback
See also the general Zulip server [troubleshooting
guide](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:
@@ -185,20 +215,12 @@ Useful logs are available in a few places:
- 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/channel/31-production-help) in the
[Zulip development community
server](https://zulip.com/development-community/) for best-effort help.
Please include the relevant error output from the above logs in a
[Markdown code
block](https://zulip.com/help/code-blocks)
in any reports.
See also the general Zulip server [troubleshooting guide](troubleshooting.md).
### Rolling back to a prior version
This rollback process is intended for minor releases (e.g., `2.0.3` to
`2.0.6`); a more complicated process is required to roll back database
This rollback process is intended for minor releases (e.g., `9.4` to
`9.3`); a more complicated process is required to roll back database
migrations before downgrading to an older major release.
The Zulip upgrade process works by creating a new deployment under
@@ -221,8 +243,8 @@ user-configured actions to run before and after an upgrade.
Files in the `/etc/zulip/pre-deploy.d` and `/etc/zulip/post-deploy.d`
directories are inspected for files ending with `.hook`, just before and after
the critical period when the server is restarted. Each file is called, sorted in
alphabetical order, from the working directory of the new version, with
the critical period when the server is restarted. Files are called from the
working directory of the new version in alphabetical order, with
environment variables as described below. If any of them exit with non-0 exit
code, the upgrade will abort.
@@ -237,8 +259,8 @@ The hook is run with the following environment variables set:
If the upgrade is upgrading between [versions in `git`][upgrade-from-git], then
the following environment variables will also be present:
- `ZULIP_OLD_COMMIT`: The full commit hash of the version being upgraded from
- `ZULIP_NEW_COMMIT`: The full commit hash of the version being upgraded to
- `ZULIP_OLD_COMMIT`: The full commit hash of the version being upgraded from.
- `ZULIP_NEW_COMMIT`: The full commit hash of the version being upgraded to.
- `ZULIP_OLD_MERGE_BASE_COMMIT`: The full commit hash of the merge-base of the
version being upgraded from, and the public branch in
[`zulip/zulip`][zulip/zulip]. This will be the closest commit in standard
@@ -262,12 +284,11 @@ 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.
You can test whether any files will be overwritten 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
@@ -275,8 +296,8 @@ 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.
can look into making the Zulip Puppet configuration flexible enough to
handle your setup.
### nginx configuration changes
@@ -289,6 +310,57 @@ and the latter for `server` contexts.
[context]: http://nginx.org/en/docs/beginners_guide.html#conf_structure
## Upgrading PostgreSQL
The major version of PostgreSQL is upgraded separately from the Zulip
server version. Further, the version of PostgreSQL included with a
Zulip server is not linked to that of the host OS; the Zulip installer
uses the latest available version of PostgreSQL at installation time
(currently, version 16).
The following table details which versions each major Zulip Server
version supports:
```{include} postgresql-support-table.md
```
To upgrade the version of PostgreSQL on the Zulip server:
1. Upgrade your Zulip server, at least to the latest Zulip maintenance
release for your major Zulip version (e.g., upgrade 9.1 to
9.4). This ensures you're using the most robust version of the
PostgreSQL upgrade tool.
1. Stop the server, as the `zulip` user:
```bash
/home/zulip/deployments/current/scripts/stop-server
```
1. Take a backup, in case of any problems:
```bash
/home/zulip/deployments/current/manage.py backup --output=/home/zulip/postgresql-upgrade.backup.tar.gz
```
1. As root, run the database upgrade tool:
```bash
/home/zulip/deployments/current/scripts/setup/upgrade-postgresql
```
1. As the `zulip` user, start the server again:
```bash
/home/zulip/deployments/current/scripts/start-server
```
You should now be able to navigate to the Zulip server's URL and
confirm everything is working correctly.
[docker-upgrade]: https://github.com/zulip/docker-zulip#upgrading-the-zulip-container
## Upgrading the operating system
When you upgrade the operating system on which Zulip is installed
@@ -751,54 +823,3 @@ confirm everything is working correctly.
9. [Upgrade from Debian 10 to 11](#upgrading-from-debian-10-to-11),
the next in chain of upgrades leading to a supported operating
system.
## Upgrading PostgreSQL
The major version of PostgreSQL is upgraded separately from the Zulip
server version. Further, the version of PostgreSQL included with a
Zulip server is not linked to that of the host OS; the Zulip installer
uses the latest available version of PostgreSQL at installation time
(currently, version 16).
The following table details which versions each major Zulip Server
version supports:
```{include} postgresql-support-table.md
```
To upgrade the version of PostgreSQL on the Zulip server:
1. Upgrade your Zulip server, at least to the latest Zulip maintenance
release for your major Zulip version (E.g., upgrade 9.1 to
9.4). This ensures you're using the most robust version of the
PostgreSQL upgrade tool.
1. Stop the server, as the `zulip` user:
```bash
/home/zulip/deployments/current/scripts/stop-server
```
1. Take a backup, in case of any problems:
```bash
/home/zulip/deployments/current/manage.py backup --output=/home/zulip/postgresql-upgrade.backup.tar.gz
```
1. As root, run the database upgrade tool:
```bash
/home/zulip/deployments/current/scripts/setup/upgrade-postgresql
```
1. As the `zulip` user, start the server again:
```bash
/home/zulip/deployments/current/scripts/start-server
```
You should now be able to navigate to the Zulip server's URL and
confirm everything is working correctly.
[docker-upgrade]: https://github.com/zulip/docker-zulip#upgrading-the-zulip-container