PostgreSQL Upgrade Instructions Incomplete

[gohrner]

The Docker Compose script was adjusted to use PostgreSQL 13, however when upgrading from a previous Docker Compose script version, extra steps have to be taken to properly migrate the DB contents.

This is also nicely explained somehow in the actual commit: https://github.com/opf/openproject-deploy/blob/stable/12/compose/control/README.md#upgrade

BUT:

These instructions seem nowhere to be found at places where users will actually look for them. Maybe I just was extraordinarily stupid, but I actually had to fetch the link from the already closed issue #13 and manually copy paste it into my browser's address bar to be able to view it... :-( This was only possible because I knew the instructions were there.

How would I be able to find it without that knowledge?

If I read the official docs, I end up at:

https://www.openproject.org/docs/installation-and-operations/operation/upgrading/#compose-based-installation

This just says

Compose-based installation
When using the Compose-based docker installation, you can simply do the following:

docker-compose pull
docker-compose up -d

Please note that you can override the TAG that is used to pull the OpenProject image from the Docker Hub.

...which will probably break the installation completely, as there's no indication for special treatment of the DB.

I might have expected a notice in the OpenProject release notes, but neither on

https://www.openproject.org/docs/release-notes/12-0-0/#drop-official-support-for-postgresql--13

nor on

https://www.openproject.org/docs/release-notes/12-0-0/#migrating-to-openproject-120 is there any indication that anything special has to be done.

And even if I find the OpenProject Docker Compose GitHub repo and view the instructions there:

https://github.com/opf/openproject-deploy/tree/stable/12/compose

there's not even a hint that anything has to be done manually to the DB.

The instructions only state:

Upgrade
Go to the compose folder:

cd openproject/compose
Retrieve any changes from the openproject-deploy repository:

git pull origin stable/12
Make sure you are using the latest version of the Docker images:

docker-compose pull
Relaunch the containers:

docker-compose up -d

...which will probably also break the installation.

How am I, as a "regular" user, supposed to find the proper upgrade instructions?

IMHO, this should be one of the first things pointed out in any upgrade instructions for OpenProject 12 Docker Compose based installations, and should be REALLY EASY to find and REALLY DIFFICULT to miss.

The current situation is completely the opposite from my point of view - the correct instructions seem to be nearly impossible to find while and official, reachable upgrade instructions seem to indicate that nothing special needs to be done at all...

[estan]

I agree. The instructions should be clear on when it is safe to use instructions in compose/README.md, and when compose/control/README.md instructions must be used instead.

Ideally there should only be one set of upgrade instructions, which should automatically upgrade PostgreSQL safely if possible, to avoid confusion. So something like compose/control, but which only attempt upgrade of PostgreSQL if necessary.

[estan]

Actually, the entrypoint for the control plane already will not attempt PostgreSQL upgrade if it is not necessary (https://github.com/opf/openproject-deploy/blob/stable/12/compose/control/upgrade/scripts/00-db-upgrade.sh#L9-L12).

So then I think upgrade instructions in compose/README.md can be removed and replaced by compose/control/README.md, because only the latter instructions are always safe (even if postgres version is bumped in openproject-deploy).

The instructions in compose/control/README.md also suggest taking a backup before upgrading, which seems to be a good idea to always do.