Please adhere to versioning scheme for container upgrades #120

New Issue

2026-08-27T09:29:29Z

stevensting commented

2026-08-27 09:29:29 +00:00

I have seen a couple of upgrades of non-nextcloud containers, namely mariadb and postgres which have major version bumps. If you do that, the convention is to also do a major release of the recipe, so operators know what is going on. Best would be to also mention that in the release notes.

dannygroenewegen commented

2026-08-28 07:54:15 +00:00

Thanks for bringing this up! I think you're right about MariaDB. I don't run that myself and haven't done those releases, but maybe @ineiti can weigh in on that? From the docs, it looks like mariadb-upgrade is needed after a major bump, or MARIADB_AUTO_UPGRADE should be added to compose.mariadb.yml to handle that automatically (if that's reliable). @ineiti did you run into this when upgrading mariadb? Should that have been a major recipe bump because of the required mariadb-upgrade?

For postgres it's different: The recipe now uses pgautoupgrade, so e.g. in release 14.1.0+33.0.7-fpm the upgrade from pgautoupgrade:14 to pgautoupgrade:17 is handled automatically, no manual prep needed. And with the recipe version being semver, I believe we should look at this from the perspective of the receipe/app/nextcloud.

The docs write "In all cases, we follow the semver semantics.", also with an example:

Since we're upgrading Wordpress from 6.9.0 -> 6.9.1, and the minor MariaDB upgrade does not change anything in our case, we consider this a patch release.

So if we're strictly following semver: pgautoupgrade14->17 while nextcloud stays on the same version is not a breaking change (the nextcloud interface stays the same), no manual work required (handled by pgautoupgrade), and does not even introduce new features (postgresql is just a dependency, nextcloud functionality stays the same). I've released this as a minor recipe version to indicate a substantial underlying change. But technically this should have been a patch release from the recipe's perspective, right?

Thanks for bringing this up! I think you're right about MariaDB. I don't run that myself and haven't done those releases, but maybe @ineiti can weigh in on that? From the docs, it looks like `mariadb-upgrade` is needed after a major bump, or `MARIADB_AUTO_UPGRADE` should be added to `compose.mariadb.yml` to handle that automatically (if that's reliable). @ineiti did you run into this when upgrading mariadb? Should that have been a major recipe bump because of the required `mariadb-upgrade`? For postgres it's different: The recipe now uses `pgautoupgrade`, so e.g. in release [14.1.0+33.0.7-fpm](https://git.coopcloud.tech/coop-cloud/nextcloud/src/tag/14.1.0+33.0.7-fpm) the upgrade from `pgautoupgrade:14` to `pgautoupgrade:17` is handled automatically, no manual prep needed. And with the recipe version being semver, I believe we should look at this from the perspective of the receipe/app/nextcloud. The [docs](https://docs.coopcloud.tech/maintainers/handbook/#how-are-recipes-versioned) write _"In all cases, we follow the semver semantics."_, also with an example: > Since we're upgrading Wordpress from 6.9.0 -> 6.9.1, and the minor MariaDB upgrade does not change anything in our case, we consider this a patch release. So if we're strictly following semver: pgautoupgrade14->17 while nextcloud stays on the same version is not a breaking change (the nextcloud interface stays the same), no manual work required (handled by pgautoupgrade), and does not even introduce new features (postgresql is just a dependency, nextcloud functionality stays the same). I've released this as a minor recipe version to indicate a substantial underlying change. But technically this should have been a patch release from the recipe's perspective, right?

ineiti commented

2026-08-28 15:23:55 +00:00

I just checked the logs, and mariadb didn't complain when going from 11.4.12 to 12.3.2.

However, https://mariadb.com/docs/server/clients-and-utilities/deployment-tools/mariadb-upgrade writes that:

You should run mariadb-upgrade after upgrading from one major MariaDB release to another, such as from MariaDB 10.11 to MariaDB 11.4. You also have to use mariadb-upgrade after migrating to MariaDB from MySQL. It's also safe to run mariadb-upgrade for minor upgrades, as, if there are no incompatibilities, nothing is changed.

So I think, yes, we should add the MARIADB_AUTO_UPGRADE=1.

Wrt patch / minor / major version bumps of the recipe version: I think both for mariadb and postgresql, it should've been a minor version bump. It's not a major new feature, the user doesn't need to do anything, but you cannot downgrade afterwards.

I just checked the logs, and mariadb didn't complain when going from `11.4.12` to `12.3.2`. However, https://mariadb.com/docs/server/clients-and-utilities/deployment-tools/mariadb-upgrade writes that: > You should run mariadb-upgrade after upgrading from one major MariaDB release to another, such as from MariaDB 10.11 to MariaDB 11.4. You also have to use mariadb-upgrade after migrating to MariaDB from MySQL. It's also safe to run mariadb-upgrade for minor upgrades, as, if there are no incompatibilities, nothing is changed. So I think, yes, we should add the `MARIADB_AUTO_UPGRADE=1`. Wrt patch / minor / major version bumps of the recipe version: I think both for mariadb and postgresql, it should've been a minor version bump. It's not a major new feature, the user doesn't need to do anything, but you cannot downgrade afterwards.

ineiti commented

2026-08-28 15:42:40 +00:00

See #121 and #122

simon commented

2026-09-02 09:51:34 +00:00

Hi there! I agree on having a consistent versioning scheme.

We run Nextcloud with MariaDB and after every upgrade (no matter if major, minor or patch) we run these:

  upgrade-hooks:
    - app run_occ db:add-missing-indices
    - app run_occ 'maintenance:repair --include-expensive'
    - db upgrade_mariadb
    - app run_occ 'upgrade'

so major MariaDB Upgrades don't bother us that much. However I did experience a lot of trouble with pgautoupgrade in other recipes, where I had to manually continue the migration in a number of containers. Didn't fix the root cause yet - something with timings and the way updates are rolled out leading to the old container not being shutdown entirely, resulting in FATAL: lock file "postmaster.pid" already exists.

bit of a sidetrack but maybe important note on reliability of database upgrades.

Hi there! I agree on having a consistent versioning scheme. We run Nextcloud with MariaDB and after every upgrade (no matter if major, minor or patch) we run these: ``` upgrade-hooks: - app run_occ db:add-missing-indices - app run_occ 'maintenance:repair --include-expensive' - db upgrade_mariadb - app run_occ 'upgrade' ``` so major MariaDB Upgrades don't bother us that much. However I did experience a lot of trouble with `pgautoupgrade` in other recipes, where I had to manually continue the migration in a number of containers. Didn't fix the root cause yet - something with timings and the way updates are rolled out leading to the old container not being shutdown entirely, resulting in ` FATAL: lock file "postmaster.pid" already exists`. bit of a sidetrack but maybe important note on reliability of database upgrades.

stevensting commented

2026-09-02 11:24:23 +00:00

I would prefer to keep the versioning scheme strict, meaning major upgrade of any container will lead to a major version bump of the recipe. This will make the bump transparent for operators. And if you wish, you can add information to the release notes, that there are no breaking changes expected as the DB should do auto updates.

👍 1

ineiti commented

2026-09-04 15:47:26 +00:00

@dannygroenewegen any preference? I'm still leaning towards using a minor patch for automatic db updates... But not by much anymore :)

dannygroenewegen commented

2026-09-07 10:30:27 +00:00

I can live with either way. @stevensting, so you propose deviating from this section of the docs by using a modified version of semver where the recipe version bump matches the version bump of any container in this recipe? So a major nginx or redis update should also be a major recipe update?

I can live with either way. @stevensting, so you propose deviating from [this section of the docs](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-reference-services-in-configs) by using a modified version of semver where the recipe version bump matches the version bump of any container in this recipe? So a major nginx or redis update should also be a major recipe update?

stevensting commented

2026-09-07 15:55:03 +00:00

I can live with either way. @stevensting, so you propose deviating from this section of the docs by using a modified version of semver where the recipe version bump matches the version bump of any container in this recipe? So a major nginx or redis update should also be a major recipe update?

If you want to call it deviation, yes. I would call it doing it by the books. ;)

> I can live with either way. @stevensting, so you propose deviating from [this section of the docs](https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-reference-services-in-configs) by using a modified version of semver where the recipe version bump matches the version bump of any container in this recipe? So a major nginx or redis update should also be a major recipe update? If you want to call it deviation, yes. I would call it doing it by the books. ;)

ineiti commented

2026-09-08 08:18:39 +00:00

I can live with either way.

Wrong answer, I wanted you to call the shots :) Anyway, looking at the history, we have this precedence:

% git diff 8.0.1+29.0.3-fpm..9.0.0+29.0.5-fpm compose.postgres.yml 
diff --git a/compose.postgres.yml b/compose.postgres.yml
index 2e24f15..7709a35 100644
--- a/compose.postgres.yml
+++ b/compose.postgres.yml
@@ -10,7 +10,7 @@ services:
       - NEXTCLOUD_UPDATE=1
 
   db:
-    image: "postgres:12"
+    image: "postgres:13"
     command: -c "max_connections=${MAX_DB_CONNECTIONS:-100}"
     volumes:
       - "postgres:/var/lib/postgresql/data"

And the nextcloud version didn't change. So it was a major coopcloud version bump for a major dependency bump. Which means that unless we want to do a revolution, we should bump the major version also for dependency major versions...

I'll update #121, and I guess the https://docs.coopcloud.tech/maintainers/handbook/#how-are-new-recipe-versions-tested should be made more explicit...

> I can live with either way. Wrong answer, I wanted you to call the shots :) Anyway, looking at the history, we have this precedence: ``` % git diff 8.0.1+29.0.3-fpm..9.0.0+29.0.5-fpm compose.postgres.yml diff --git a/compose.postgres.yml b/compose.postgres.yml index 2e24f15..7709a35 100644 --- a/compose.postgres.yml +++ b/compose.postgres.yml @@ -10,7 +10,7 @@ services: - NEXTCLOUD_UPDATE=1 db: - image: "postgres:12" + image: "postgres:13" command: -c "max_connections=${MAX_DB_CONNECTIONS:-100}" volumes: - "postgres:/var/lib/postgresql/data" ``` And the nextcloud version didn't change. So it was a major coopcloud version bump for a major dependency bump. Which means that unless we want to do a revolution, we should bump the major version also for dependency major versions... I'll update #121, and I guess the https://docs.coopcloud.tech/maintainers/handbook/#how-are-new-recipe-versions-tested should be made more explicit...

👍 1

ineiti referenced this issue

2026-09-08 08:19:36 +00:00

Details about semver of the recipe #121

ineiti referenced this issue

2026-09-08 08:22:55 +00:00

Details about semver of the recipe #121

moritz commented

2026-09-09 23:52:38 +00:00

I would prefer to have versions with specific meanings than just doing it by the books.
For me a major version might possibly break something. In many configurations major updates are stopped from automatically go through the pipeline and require a manual review. And this really depends on the image. If the update to the next major version of some images like mariadb, pgautoupgrade or redis is 100% safe to not break something I would prefer to not release a new major version that requires the manual review process.
Maybe first it's more time to decide which images could get major updates without making a major release than having a strict policy for all images, but longterm it saves a lot of time to not review each single major redis update manually.

I would prefer to have versions with specific meanings than just doing it by the books. For me a major version might possibly break something. In many configurations major updates are stopped from automatically go through the pipeline and require a manual review. And this really depends on the image. If the update to the next major version of some images like mariadb, pgautoupgrade or redis is 100% safe to not break something I would prefer to not release a new major version that requires the manual review process. Maybe first it's more time to decide which images could get major updates without making a major release than having a strict policy for all images, but longterm it saves a lot of time to not review each single major redis update manually.

stevensting commented

2026-09-10 09:18:27 +00:00

I would prefer to have versions with specific meanings than just doing it by the books.
For me a major version might possibly break something. In many configurations major updates are stopped from automatically go through the pipeline and require a manual review. And this really depends on the image. If the update to the next major version of some images like mariadb, pgautoupgrade or redis is 100% safe to not break something I would prefer to not release a new major version that requires the manual review process.
Maybe first it's more time to decide which images could get major updates without making a major release than having a strict policy for all images, but longterm it saves a lot of time to not review each single major redis update manually.

In theory I would agree, but in practice I highly doubt that we have enough capacity to test this good enough to be confident that this will work for everyone. Didn't you have problems with pgautoupgrade?
I mean putting the major version marker gives everyone the freedom to decide what they want to do: Just run it anyway, deploy it on a test system etc. And redis also only has a new major version every couple of years.
But I would be ok with collectively deciding on exceptions where no major version bump is necessary, e.g. redis would be ok for me I guess, for DB containers I would be more hesitant.

> I would prefer to have versions with specific meanings than just doing it by the books. > For me a major version might possibly break something. In many configurations major updates are stopped from automatically go through the pipeline and require a manual review. And this really depends on the image. If the update to the next major version of some images like mariadb, pgautoupgrade or redis is 100% safe to not break something I would prefer to not release a new major version that requires the manual review process. > Maybe first it's more time to decide which images could get major updates without making a major release than having a strict policy for all images, but longterm it saves a lot of time to not review each single major redis update manually. In theory I would agree, but in practice I highly doubt that we have enough capacity to test this good enough to be confident that this will work for everyone. Didn't you have problems with pgautoupgrade? I mean putting the major version marker gives everyone the freedom to decide what they want to do: Just run it anyway, deploy it on a test system etc. And redis also only has a new major version every couple of years. But I would be ok with collectively deciding on exceptions where no major version bump is necessary, e.g. redis would be ok for me I guess, for DB containers I would be more hesitant.

dannygroenewegen commented

2026-09-10 10:26:59 +00:00

It's unclear to me how we would decide what to do, even within a maintainer team. I guess something like the federation's consensus-based decision-making is the closest thing we have to a process for this? So here's a new proposal (for putting into MAINTENANCE.md), hopefully incorporating all perspectives:

Semver versioning within this recipe

The recipe version itself is updated according to the following guidelines. These describe the minimum required bump for a given kind of change. The actual impact of any change (an image update or, e.g. a compose or config change) should always be considered, and the recipe version can always be bumped higher than the guideline below to match the impact of the change.

For updates of the image in the app container (nextcloud), we match the recipe version bump to at least the image version bump.

Other containers in this recipe are considered dependencies of the app container unless they expose additional functionality directly.

For image updates of dependency containers, we judge the recipe version bump from the perspective of the app itself, but a minor or major update of a dependent container is always reflected by at least a minor recipe version bump to indicate a substantial update under the hood.

Temporary exception:

In the past, there have been issues with upgrades from database containers (before the pgautoupgrade image and MARIADB_AUTO_UPGRADE setting). We continue treating a major update of a database container (postgresql, mariadb) as a major recipe bump until that database has had two consecutive major upgrades with no issues reported, building trust in its automatic upgrade. Once that trust is established for a given database, we continue with the default guidelines above.

Can everyone live with this, or is there something that's still missing?

It's unclear to me how we would decide what to do, even within a maintainer team. I guess something like the federation's consensus-based decision-making is the closest thing we have to a process for this? So here's a new proposal (for putting into `MAINTENANCE.md`), hopefully incorporating all perspectives: > ## Semver versioning within this recipe > The recipe version itself is updated according to the following guidelines. These describe the minimum required bump for a given kind of change. The actual impact of any change (an image update or, e.g. a compose or config change) should always be considered, and the recipe version can always be bumped higher than the guideline below to match the impact of the change. > > - For updates of the image in the app container (nextcloud), we match the recipe version bump to at least the image version bump. > - Other containers in this recipe are considered dependencies of the app container unless they expose additional functionality directly. > - For image updates of dependency containers, we judge the recipe version bump from the perspective of the app itself, but a minor or major update of a dependent container is always reflected by at least a minor recipe version bump to indicate a substantial update under the hood. > > Temporary exception: > - In the past, there have been issues with upgrades from database containers (before the `pgautoupgrade` image and `MARIADB_AUTO_UPGRADE` setting). We continue treating a major update of a database container (postgresql, mariadb) as a major recipe bump until that database has had two consecutive major upgrades with no issues reported, building trust in its automatic upgrade. Once that trust is established for a given database, we continue with the default guidelines above. Can everyone live with this, or is there something that's still missing?

❤️ 1

ineiti commented

2026-09-10 15:55:09 +00:00

Can everyone live with this, or is there something that's still missing?

Wow - do you work in diplomacy? Chef's kiss, I think it's marvellous.

I hope we won't spend ages debating whether it's a minor or major bump :)

> Can everyone live with this, or is there something that's still missing? Wow - do you work in diplomacy? Chef's kiss, I think it's marvellous. I hope we won't spend ages debating whether it's a minor or major bump :)

Sign in to join this conversation.

Branches Tags

main

renovate/docker.elastic.co-elasticsearch-elasticsearch-9.x

semver_details

nextcloud-metrics

trusted-domains

update_33.0.8

renovate/pgautoupgrade-pgautoupgrade-18.x

pr-15.2.0+34.0.2-fpm

pr-14.1.0+33.0.7-fpm

pr-14.2.0+33-fpm

pr-15.1.0+34.0.2-fpm

pr-15.0.0+34.0.2-fpm

pr-14.0.1+33.0.7-fpm

feat/check-major-upgrade

pr-14.0.0+33-fpm

temp

fix/nginx-conf-config-name

pr-13.2.0+32-fpm

upload-limit

feature/imaginary

kc_stable

nextcloud-v28

add-theming-v28.0.5

add-theming

update-nginx-conf

split-bbb-onlyoffice-compos

split-onlyoffice-bbb-config

authentik_sso

healthchecks

occ_cmds

auto_app_install

embed_nextcloud_in_iframe

auto_configure_sso

add-postgres-db

5 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: coop-cloud/nextcloud#120