PostgreSQL Upgrade Instructions Incomplete

Open
  • Is something wrong?
#16 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
48/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
docker-compose, postgresql
Domain
databases, devops, documentation

Research direction

Start with stable/12/compose/control/README.md and the Compose-based installation upgrade section in the official documentation. Compare those instructions with the PostgreSQL migration steps linked from the issue and the relevant release notes. Done means users can find prominent, consistent upgrade guidance, including the required database migration steps.

Written by the indexing model from the issue text.

Description

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...

Dominant language
Shell
Stars
347
Forks
319
No merged PRs in 30d

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from opf/openproject-docker-compose

All issues in opf/openproject-docker-compose

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.