From 16ed3459ff4b55096180ea1fe2b6332f4ee7aa26 Mon Sep 17 00:00:00 2001 From: Alex Vandiver Date: Mon, 5 Dec 2022 19:00:08 -0500 Subject: [PATCH] UPGRADING: Split out of README.md. --- README.md | 191 ++------------------------------------------------- UPGRADING.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 190 insertions(+), 186 deletions(-) create mode 100644 UPGRADING.md diff --git a/README.md b/README.md index 79b94b7..842b794 100644 --- a/README.md +++ b/README.md @@ -298,6 +298,11 @@ to `/etc/ssl/certs/ca-certificates.crt`. At this point you are ready to build Zulip. +### Upgrading + +See the [separate upgrading document](UPGRADING.md) for upgrading +instructions. + ## Running a Zulip server with Kubernetes A Kubernetes pod file is in the `kubernetes/` folder; you can run it @@ -351,192 +356,6 @@ is behind a load balancer and you need the Zulip server to respond over HTTP, you can configure that via setting `DISABLE_HTTPS: "True"` in the Docker environment (`docker-compose.yml`). -## 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`. - -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 -`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. - -### 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/`. - - Note that `docker-zulip` did not support for Zulip's built-in - `restore-backup` tool before Zulip 3.0. - -1. Pull the new image version, e.g. for `2.0.8` run: `docker pull zulip/docker-zulip:2.0.8-0`. 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). - - **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.: - -```yml -zulip: - image: "zulip/docker-zulip:2.0.1-0" -``` - -4. You can execute the upgrade by running: - -``` -# Stops the old zulip container; this begins your downtime -docker-compose stop -# Boots the new zulip container; this ends your downtime -docker-compose up -# Deletes the old container images -docker-compose rm -``` - -That's it! Zulip is now running the updated version. -You can confirm you're running the latest version by running: - -```bash -docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.py -``` - -### 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.: - -``` - zulip: - # image: "zulip/docker-zulip:2.0.1-0" - build: - context: . - args: - # Change these if you want to build zulip from a different repo/branch - ZULIP_GIT_URL: https://github.com/zulip/zulip.git - ZULIP_GIT_REF: master -``` - -You can set `ZULIP_GIT_URL` to any clone of the zulip/zulip git -repository, 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. - -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 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. - -### 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` -Postgres image, you need to run a few manual steps to upgrade to the -`zulip/zulip-postgresql` Postgres image (because we've significantly -upgraded the major postgres version). - -These instructions assume that you have not changed the default -Postgres 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 Postgres data dir. - -2. Stop all Zulip containers, except the postgres one (e.g. use - `docker stop` and not `docker-compose stop`). - -3. Create a new (upgraded) Postgres container using a different data directory: - -``` -docker run -d \ - --name postgresnew \ - -e POSTGRES_DB=zulip \ - -e POSTGRES_USER=zulip \ - -e POSTGRES_PASSWORD=zulip \ - -v /opt/docker/zulip/postgresql/new:/var/lib/postgresql/data:rw \ - zulip/zulip-postgresql:latest -``` - -4. Use `pg_dumpall` to dump all data from the existing Postgres container to - the new Postgres container: - -``` -docker-compose exec database pg_dumpall -U postgres | \ - docker exec -i postgresnew psql -U postgres -``` - -5. Stop and remove both Postgres containers: - -``` -docker-compose rm --stop database -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`). - -7. Replace the old Postgres data directory with upgraded data directory: - -``` -mv /opt/docker/zulip/postgresql/data /opt/docker/zulip/postgresql/old -mv /opt/docker/zulip/postgresql/new /opt/docker/zulip/postgresql/data -``` - -8. Delete the old existing containers: - -``` -docker-compose rm -``` - -9. Start Zulip up again: - -``` -docker-compose up -``` - -That should be it. Your Postgres data has now been updated to use the -`zulip/zulip-postgresql` image. - ## Troubleshooting Common issues include: diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000..482c834 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,185 @@ +## 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`. + +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 +`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. + +### 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/`. + + Note that `docker-zulip` did not support for Zulip's built-in + `restore-backup` tool before Zulip 3.0. + +1. Pull the new image version, e.g. for `2.0.8` run: `docker pull zulip/docker-zulip:2.0.8-0`. 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). + + **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.: + +```yml +zulip: + image: "zulip/docker-zulip:2.0.1-0" +``` + +4. You can execute the upgrade by running: + +``` +# Stops the old zulip container; this begins your downtime +docker-compose stop +# Boots the new zulip container; this ends your downtime +docker-compose up +# Deletes the old container images +docker-compose rm +``` + +That's it! Zulip is now running the updated version. +You can confirm you're running the latest version by running: + +```bash +docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.py +``` + +### 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.: + +``` + zulip: + # image: "zulip/docker-zulip:2.0.1-0" + build: + context: . + args: + # Change these if you want to build zulip from a different repo/branch + ZULIP_GIT_URL: https://github.com/zulip/zulip.git + ZULIP_GIT_REF: master +``` + +You can set `ZULIP_GIT_URL` to any clone of the zulip/zulip git +repository, 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. + +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 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. + +### 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` +Postgres image, you need to run a few manual steps to upgrade to the +`zulip/zulip-postgresql` Postgres image (because we've significantly +upgraded the major postgres version). + +These instructions assume that you have not changed the default +Postgres 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 Postgres data dir. + +2. Stop all Zulip containers, except the postgres one (e.g. use + `docker stop` and not `docker-compose stop`). + +3. Create a new (upgraded) Postgres container using a different data directory: + +``` +docker run -d \ + --name postgresnew \ + -e POSTGRES_DB=zulip \ + -e POSTGRES_USER=zulip \ + -e POSTGRES_PASSWORD=zulip \ + -v /opt/docker/zulip/postgresql/new:/var/lib/postgresql/data:rw \ + zulip/zulip-postgresql:latest +``` + +4. Use `pg_dumpall` to dump all data from the existing Postgres container to + the new Postgres container: + +``` +docker-compose exec database pg_dumpall -U postgres | \ + docker exec -i postgresnew psql -U postgres +``` + +5. Stop and remove both Postgres containers: + +``` +docker-compose rm --stop database +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`). + +7. Replace the old Postgres data directory with upgraded data directory: + +``` +mv /opt/docker/zulip/postgresql/data /opt/docker/zulip/postgresql/old +mv /opt/docker/zulip/postgresql/new /opt/docker/zulip/postgresql/data +``` + +8. Delete the old existing containers: + +``` +docker-compose rm +``` + +9. Start Zulip up again: + +``` +docker-compose up +``` + +That should be it. Your Postgres data has now been updated to use the +`zulip/zulip-postgresql` image.