From e065ed603c3d84bc13c71624bc57050c02ee2eec Mon Sep 17 00:00:00 2001 From: Alex Vandiver Date: Mon, 5 Dec 2022 19:15:26 -0500 Subject: [PATCH] UPGRADING: Re-wrap. --- UPGRADING.md | 116 +++++++++++++++++++++++++-------------------------- 1 file changed, 56 insertions(+), 60 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 26c0d13..7ffac8d 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,30 +1,28 @@ ## Upgrading the Zulip container -You can upgrade your Zulip installation to any newer version of Zulip -with the following instructions. At a high level, the strategy is to -download a new image, stop the `zulip` container, and then boot it -back up with the new image. When the upgraded `zulip` container boots -the first time, it will run the necessary database migrations with -`manage.py migrate`. +You can upgrade your Zulip installation to any newer version of Zulip with the +following instructions. At a high level, the strategy is to download a new +image, stop the `zulip` container, and then boot it back up with the new +image. When the upgraded `zulip` container boots the first time, it will run the +necessary database migrations with `manage.py migrate`. -If you ever find you need to downgrade your Zulip server, you'll need -to use `manage.py migrate` to downgrade the database schema manually. +If you ever find you need to downgrade your Zulip server, you'll need to use +`manage.py migrate` to downgrade the database schema manually. -If you are using old `galexrt/docker-zulip` images (from Zulip 1.8.1 or -older), you need to upgrade the postgres image from +If you are using old `galexrt/docker-zulip` images (from Zulip 1.8.1 or older), +you need to upgrade the postgres image from `quay.io/galexrt/postgres-zulip-tsearchextras:latest`. Refer to the -[instructions for upgrading from the old galexrt/docker-zulip](#upgrading-from-the-old-galexrtdocker-zulip) -section. +[instructions for upgrading from the old +galexrt/docker-zulip](#upgrading-from-the-old-galexrtdocker-zulip) section. ### Using `docker-compose` -0. (Optional) Upgrading does not delete your data, but it's generally - good practice to - [back up your Zulip data](http://zulip.readthedocs.io/en/latest/prod-maintain-secure-upgrade.html#backups) - before upgrading to make switching back to the old version - simple. You can find your docker data volumes by looking at the - `volumes` lines in `docker-compose.yml` - e.g. `/opt/docker/zulip/postgresql/data/`. +0. (Optional) Upgrading does not delete your data, but it's generally good + practice to [back up your Zulip + data](http://zulip.readthedocs.io/en/latest/prod-maintain-secure-upgrade.html#backups) + before upgrading to make switching back to the old version simple. You can + find your docker data volumes by looking at the `volumes` lines in + `docker-compose.yml` e.g. `/opt/docker/zulip/postgresql/data/`. Note that `docker-zulip` did not support for Zulip's built-in `restore-backup` tool before Zulip 3.0. @@ -38,22 +36,21 @@ section. We recommend always upgrading to the latest minor release within a major release series. -2. Update this project to the corresponding `docker-zulip` version and - resolve any merge conflicts in `docker-compose.yml`. - This is important as new Zulip releases may require additional - settings to be specified in `docker-compose.yml` - (E.g. authentication settings for `memcached` became mandatory in - the `2.1.2` release). +2. Update this project to the corresponding `docker-zulip` version and resolve + any merge conflicts in `docker-compose.yml`. This is important as new Zulip + releases may require additional settings to be specified in + `docker-compose.yml` (E.g. authentication settings for `memcached` became + mandatory in the `2.1.2` release). - **Note:** Do not make any changes to the database version or - volume. If there is a difference in database version, leave those - unchanged for now, and complete that upgrade separately after the - Zulip upgrade; see [the section below][pg-upgrade]. + **Note:** Do not make any changes to the database version or volume. If there + is a difference in database version, leave those unchanged for now, and + complete that upgrade separately after the Zulip upgrade; see [the section + below][pg-upgrade]. [pg-upgrade]: #upgrading-zulipzulip-postgresql-to-14 -3. Verify that your updated `docker-compose.yml` points to the desired image version, - e.g.: +3. Verify that your updated `docker-compose.yml` points to the desired image + version, e.g.: ```yaml zulip: @@ -80,9 +77,8 @@ docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.p ### Upgrading from a Git repository -1. Edit `docker-compose.yml` to comment out the `image` line, and - specify the Git commit you'd like to build the zulip container from. - E.g.: +1. Edit `docker-compose.yml` to comment out the `image` line, and specify the + Git commit you'd like to build the zulip container from. E.g.: ```yaml zulip: @@ -99,44 +95,44 @@ docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.p and `ZULIP_GIT_REF` to be any ref name in that repository (e.g. `master` or `1.9.0` or `445932cc8613c77ced023125248c8b966b3b7528`). -2. Run `docker-compose build zulip` to build a Zulip Docker image from - the specified Git version. +2. Run `docker-compose build zulip` to build a Zulip Docker image from the + specified Git version. Then stop and restart the container as described in the previous section. ### Upgrading zulip/zulip-postgresql to 14 -The Docker Compose configuration for version 6.0-0 and higher default -to using PostgreSQL 14, as the previously-used PostgreSQL 10 is no -longer supported. Because the data is specific to the version of -PostgreSQL which is running, it must be dumped and re-loaded into a -new volume to upgrade. PostgreSQL 14 will refuse to start if provided -with un-migrated data from PostgreSQL 10. +The Docker Compose configuration for version 6.0-0 and higher default to using +PostgreSQL 14, as the previously-used PostgreSQL 10 is no longer +supported. Because the data is specific to the version of PostgreSQL which is +running, it must be dumped and re-loaded into a new volume to +upgrade. PostgreSQL 14 will refuse to start if provided with un-migrated data +from PostgreSQL 10. The provided `upgrade-postgresql` tool will dump the contents of the -`postgresql` image's volume, create a new PostgreSQL 14 volume, -perform the necessary migration, update the `docker-compose.yml` -file to match, and re-start Zulip. +`postgresql` image's volume, create a new PostgreSQL 14 volume, perform the +necessary migration, update the `docker-compose.yml` file to match, and re-start +Zulip. ### Upgrading from the old galexrt/docker-zulip -If you are using an earlier version of `galexrt/docker-zulip` which -used the `quay.io/galexrt/postgres-zulip-tsearchextras:latest` -PostgreSQL image, you need to run a few manual steps to upgrade to the -`zulip/zulip-postgresql` PostgreSQL image (because we've significantly -upgraded the major postgres version). +If you are using an earlier version of `galexrt/docker-zulip` which used the +`quay.io/galexrt/postgres-zulip-tsearchextras:latest` PostgreSQL image, you need +to run a few manual steps to upgrade to the `zulip/zulip-postgresql` PostgreSQL +image (because we've significantly upgraded the major postgres version). -These instructions assume that you have not changed the default -PostgreSQL data path (`/opt/docker/zulip/postgresql/data`) in your -`docker-compose.yml`. If you have changed it, please replace all -occurences of `/opt/docker/zulip/postgresql/data` with your path. +These instructions assume that you have not changed the default PostgreSQL data +path (`/opt/docker/zulip/postgresql/data`) in your `docker-compose.yml`. If you +have changed it, please replace all occurences of +`/opt/docker/zulip/postgresql/data` with your path. 1. Make a backup of your Zulip PostgreSQL data dir. -2. Stop all Zulip containers, except the postgres one (e.g. use - `docker stop` and not `docker-compose stop`). +2. Stop all Zulip containers, except the postgres one (e.g. use `docker stop` + and not `docker-compose stop`). -3. Create a new (upgraded) PostgreSQL container using a different data directory: +3. Create a new (upgraded) PostgreSQL container using a different data + directory: ```shell docker run -d \ @@ -163,9 +159,9 @@ occurences of `/opt/docker/zulip/postgresql/data` with your path. docker rm --stop postgresnew ``` -6. Edit your `docker-compose.yml` to use the - `zulip/zulip-postgresql:latest` image for the `database` container - (this is the default in `zulip/docker-zulip`). +6. Edit your `docker-compose.yml` to use the `zulip/zulip-postgresql:latest` + image for the `database` container (this is the default in + `zulip/docker-zulip`). 7. Replace the old PostgreSQL data directory with upgraded data directory: