From 53de96eca2d03fe1df158607d0ddc9186a5ba887 Mon Sep 17 00:00:00 2001
From: Alex Vandiver <alexmv@zulip.com>
Date: Mon, 5 Dec 2022 19:27:37 -0500
Subject: [PATCH] UPGRADING: Document managed-volume and PostgreSQL upgrades.

This returns the manual steps for upgrading PostgreSQL which were
removed in cd348fb0937e, and documents the steps required to move a
docker-compose deploy to using Docker-managed volumes.
---
 UPGRADING.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 103 insertions(+), 11 deletions(-)

diff --git a/UPGRADING.md b/UPGRADING.md
index a648d2c..6363663 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -97,19 +97,111 @@ docker-compose exec -u zulip zulip cat /home/zulip/deployments/current/version.p
 
 Then stop and restart the container as described in the previous section.
 
-## Upgrading zulip/zulip-postgresql to 14
+## Upgrading to use Docker volumes (version 6.0-0 and above)
 
-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.
+As of Docker Zulip 6.0-0, we have switched the volume storage from being in
+directories under `/opt/docker/zulip/` on the Docker host system, to using named
+Docker managed volumes. In your `docker-compose.yml`, you should either preserve
+the previous `/opt/docker/zulip/` paths for your volumes, or migrate the
+contents to individual Docker volumes.
 
-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.
+If you elect to switch to managed Docker volumes, you can copy the data out of
+`/opt/docker/zulip` and onto managed volumes using the following:
+
+```shell
+# Stop the containers
+docker-compose stop
+
+# Copy the data into new managed volumes:
+zulip_volume_sync() { docker run -it --rm -v "/opt/docker/zulip/$1:/src" -v "$(basename "$(pwd)")_${2:$1}":/dst ubuntu:20.04 sh -c 'cd /src; cp -a . /dst' ; }
+zulip_volume_sync postgresql postgresql-10
+zulip_volume_sync zulip
+zulip_volume_sync rabbitmq
+zulip_volume_sync redis
+
+# Edit your `docker-compose.yml` to use, e.g. `postgresql-10:/var/lib/postgresql/data:rw`
+# rather than `/opt/docker/zulip/postgresql/data:/var/lib/postgresql/data:rw` as a volume.
+$EDITOR docker-compose.yml
+
+# Start the containers again
+docker-compose start
+```
+
+## Upgrading zulip/zulip-postgresql to 14 (version 6.0-0 and above)
+
+As of Docker Zulip 6.0-0, we have upgraded the version of PostgreSQL which our
+docker-compose configuration uses, from PostgreSQL 10 (which is no longer
+supported) to PostgreSQL 14. Because the on-disk storage is not compatible
+between PostgreSQL versions, this requires more than simply switching which
+PostgreSQL docker image is used — the data must be dumped from PostgreSQL 10,
+and imported into a running PostgreSQL 14.
+
+You should not adjust the `image` of the database when upgrading to Zulip Server
+6.0.
+
+After upgrading the `zulip` service, using the usual steps, to the
+`zulip/docker-zulip:6.0-0` tag, you can upgrade the PostgreSQL image version by
+running the included `./upgrade-postgresql` tool. This will create a
+Docker-managed volume named `postgresql-14` to store its data, and will adjust
+the `docker-compose.yml` file to use that.
+
+If the tool does not work, or you would prefer to perform the steps manually,
+see the steps below. 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 occurrences of
+`/opt/docker/zulip/postgresql/data` with your path, or volume.
+
+1. Make a backup of your Zulip Postgres data directory.
+
+2. Stop the Zulip container:
+
+   ```shell
+   docker-compose stop zulip
+   ```
+
+3. Create a new (upgraded) Postgres container using a different data directory:
+
+   ```shell
+   docker run -d \
+         --name postgresnew \
+         -e POSTGRES_DB=zulip \
+         -e POSTGRES_USER=zulip \
+         -e POSTGRES_PASSWORD=zulip \
+         -v "$(basename "$(pwd)")_postgresql-14:/var/lib/postgresql/data:rw" \
+         zulip/zulip-postgresql:14
+   ```
+
+4. Use `pg_dumpall` to dump all data from the existing Postgres container to the
+   new Postgres container, and reset the password (for SCRAM-SHA-256 auth
+   upgrade):
+
+   ```shell
+   docker-compose exec database pg_dumpall -U zulip | \
+       docker exec -i postgresnew psql -U zulip
+
+   echo "ALTER USER zulip WITH PASSWORD 'REPLACE_WITH_SECURE_POSTGRES_PASSWORD';" |
+       docker exec -i postgresnew psql -U zulip
+   ```
+
+5. Stop and remove both Postgres containers:
+
+   ```shell
+   docker-compose rm --stop database
+   docker stop postgresnew
+   docker rm postgresnew
+   ```
+
+6. Edit your `docker-compose.yml` to use the `zulip/zulip-postgresql:14` image
+   for the `database` container.
+
+7. Edit your `docker-compose.yml` to provide
+   `postgresql-14:/var/lib/postgresql/data:rw` as the `volume` for the
+   `database` service.
+
+8. Start Zulip up again:
+   ```shell
+   docker-compose up
+   ```
 
 ## Upgrading from the old galexrt/docker-zulip