From 2fb279d96abcb173e699859e31a64fcabe530b12 Mon Sep 17 00:00:00 2001 From: Danny Groenewegen Date: Sun, 9 Aug 2026 22:03:22 +0200 Subject: [PATCH] feat: add check_major_upgrade abra.sh function to check readiness for the next major Checks version skip, pending DB upgrade, occ update:check status, and non-shipped app compatibility (with an apps.nextcloud.com fallback lookup) to verify if it looks safe to upgrade to the next Nextcloud major version. --- README.md | 44 +++++++++++++- abra.sh | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++- release/next | 1 + 3 files changed, 201 insertions(+), 3 deletions(-) create mode 100644 release/next diff --git a/README.md b/README.md index dd86ffa..e0466f8 100644 --- a/README.md +++ b/README.md @@ -130,9 +130,49 @@ To disable dashboard app (since it is so corporate): - Configure a `defaultapp` in your `config.php` or use [apporder](https://apps.nextcloud.com/apps/apporder) ## Upgrading Nextcloud -Upgrading Nextcloud can be a hair raising experiance. They [don't support downgrading](https://docs.nextcloud.com/server/latest/admin_manual/maintenance/upgrade.html) even for minor versions. -Many of us have found that jumping major versions when upgrading is also a bad idea. We have however found that it's ok to skip minor version upgrades and go to the last minor version before a major version (e.g. 24.0.0 to 24.9.9 before going to 25.0.0). To extra cautious just upgrade one release at a time. Read the release notes and check your logs. +Upgrading Nextcloud can be a hair raising experiance. They +[don't support downgrading](https://docs.nextcloud.com/server/latest/admin_manual/maintenance/upgrade.html) +even for minor versions. + +### Upgrade path + +Many of us have found that jumping major versions when upgrading is a bad idea. +We have however found that it's ok to skip minor version upgrades and go to the +last minor version before a major version (e.g. 24.0.0 to 24.9.9 before going to +25.0.0). To be extra cautious just upgrade one release at a time. Read the +release notes and check your logs. + +### Checking upgrade readiness + +Before upgrading to a new major, check whether the instance (and its enabled +apps) look ready: + +`abra app cmd app check_major_upgrade` + +This checks that you're not skipping a major version, that there's no pending DB +upgrade left over from a previous update, and that every enabled non-shipped app +declares support for the target major (falling back to an apps.nextcloud.com +lookup to see if an app update would fix it). Shipped apps (`files`, `settings`, +etc.) are skipped since they come bundled and are upgraded within the Docker +image. Pass an explicit target major as the first argument (e.g. +`check_major_upgrade 33`) to check readiness for a specific major, or it +defaults to current major + 1. This is a sanity check, not a guarantee. Still +read Nextcloud's release notes for any +[critical changes between major versions](https://docs.nextcloud.com/server/stable/admin_manual/release_notes/index.html#critical-changes). + +### Staying on an old major version + +If you're not able to move to a new major version yet (e.g. because of app +incompatibility), note that (starting from v32) before we release a recipe +container a new major Nextcloud version, we also publish one more release of the +previous major that points its image at the floating `nextcloud:XX-fpm` tag +(e.g. `nextcloud:32-fpm`) instead of a pinned patch version. Deploying that +release is less predictable: every redeploy pulls whatever the latest `32-fpm` +build happens to be at that moment, rather than a fixed, reproducible version. +But it means you keep getting security patches for the old major if you can't +move to the next major. See [MAINTENANCE.md](./MAINTENANCE.md#release-cadence) +for how this fits into our release process. ## Upgrading Nextcloud apps (plug-ins) diff --git a/abra.sh b/abra.sh index af39f71..f201ab7 100644 --- a/abra.sh +++ b/abra.sh @@ -10,7 +10,8 @@ export CRONTAB_VERSION=v1 export PG_BACKUP_VERSION=v2 run_occ() { - su -p www-data -s /bin/sh -c "/var/www/html/occ $@" + # NOTE: uses $* (not $@) so this still works when called with multiple args as seperate words. + su -p www-data -s /bin/sh -c "/var/www/html/occ $*" } install_apps() { @@ -193,3 +194,159 @@ set_windowsfriendly_filenames() { upgrade_mariadb() { mariadb-upgrade -p`cat /run/secrets/db_root_password` } + +# Checks whether this instance looks ready to update to the next Nextcloud +# major version. +# +# Usage: +# abra app cmd app check_major_upgrade +# abra app cmd app check_major_upgrade 33 # check readiness for a specific target +# +# What it checks: +# - current version is exactly one major behind the target +# - no pending DB upgrade from a previous, unfinished update +# - whether a newer release is available on the current major +# (recommended before upgradeing to the next major) +# - every enabled, non-shipped app's compatibility with the target major +# - for apps that don't, whether apps.nextcloud.com already has a newer +# release that does +# +# It does NOT check every precondition, always read the release notes +# from Nextcloud too. +check_major_upgrade() { + target_major=$1 + + echo "=== Nextcloud major upgrade readiness check ===" + + status_json=$(run_occ status --output=json 2>/dev/null) + if [ -z "$status_json" ]; then + echo "[FAIL] Could not read 'occ status' - is Nextcloud installed and reachable?" + return 1 + fi + + current_version=$(echo "$status_json" | php -r '$d=json_decode(stream_get_contents(STDIN),true); echo $d["versionstring"] ?? "";') + current_major=${current_version%%.*} + needs_db_upgrade=$(echo "$status_json" | php -r '$d=json_decode(stream_get_contents(STDIN),true); echo ($d["needsDbUpgrade"] ?? false) ? "true" : "false";') + + if [ -z "$current_major" ]; then + echo "[FAIL] Could not determine the current Nextcloud version from 'occ status'." + return 1 + fi + + if [ -z "$target_major" ]; then + target_major=$((current_major + 1)) + fi + + echo "Current version: $current_version" + echo "Target major version: $target_major" + + ok=true + + if [ "$target_major" -le "$current_major" ]; then + echo "[FAIL] Target major ($target_major) is not newer than the current major ($current_major)." + ok=false + elif [ "$target_major" -gt "$((current_major + 1))" ]; then + echo "[FAIL] Cannot skip major versions. Upgrade to $((current_major + 1)) first." + ok=false + fi + + if [ "$needs_db_upgrade" = "true" ]; then + echo "[FAIL] A pending database upgrade was detected. Run 'occ upgrade' for the current version first." + ok=false + fi + + echo + echo "--- occ update:check ---" + update_check_output=$(run_occ "update:check" 2>&1) + if [ -z "$update_check_output" ]; then + echo "[WARN] 'occ update:check' produced no output, could not verify." + elif echo "$update_check_output" | grep -q "Everything up to date"; then + echo "[OK] Everything up to date." + else + available_version=$(echo "$update_check_output" | grep -oE 'Nextcloud [0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1 | awk '{print $2}') + available_major=${available_version%%.*} + if [ -z "$available_major" ]; then + echo "[WARN] Could not parse 'occ update:check' output to determine the available version." + elif [ "$available_major" = "$current_major" ]; then + echo "[WARN] $available_version is available on the current major. Recommended to update to that before upgrading to $target_major." + else + echo "[OK] Already on the latest release of major $current_major (next available update is $available_version)." + fi + fi + echo + + echo "--- Non-shipped app compatibility with Nextcloud $target_major ---" + echo "(shipped apps are skipped, they come bundled with the docker image)" + apps_json=$(run_occ "app:list --shipped=false --enabled --output=json" 2>/dev/null) + + if [ -z "$apps_json" ]; then + echo "[WARN] 'occ app:list' returned no output, could not check non-shipped app compatibility." + enabled_apps="" + else + apps_json_valid=$(echo "$apps_json" | php -r '$d=json_decode(stream_get_contents(STDIN),true); echo (json_last_error() === JSON_ERROR_NONE && is_array($d)) ? "1" : "0";') + if [ "$apps_json_valid" != "1" ]; then + echo "[WARN] Could not parse 'occ app:list' output, could not check non-shipped app compatibility." + enabled_apps="" + else + enabled_apps=$(echo "$apps_json" | php -r '$d=json_decode(stream_get_contents(STDIN),true); foreach(array_keys($d["enabled"] ?? []) as $a) echo $a."\n";') + if [ -z "$enabled_apps" ]; then + echo "No non-shipped apps are enabled - nothing to check here." + fi + fi + fi + + compatible_apps="" + compatible_apps_fetched=0 + + for app in $enabled_apps; do + info_file=$(find /var/www/html/apps /var/www/html/custom_apps -maxdepth 3 -type f -ipath "*/$app/appinfo/info.xml" 2>/dev/null | head -n1) + + if [ -z "$info_file" ]; then + echo "[WARN] $app: could not locate appinfo/info.xml, skipping" + continue + fi + + max_version=$(php -r ' + $x = @simplexml_load_file($argv[1]); + $dep = $x ? ($x->dependencies->nextcloud ?? null) : null; + echo $dep !== null ? (string)$dep["max-version"] : ""; + ' "$info_file") + + if [ -z "$max_version" ]; then + echo "[WARN] $app: no max-version declared in info.xml, assume compatible but verify manually" + continue + fi + + if [ "${max_version%%.*}" -ge "$target_major" ] 2>/dev/null; then + echo "[OK] $app: installed version supports up to Nextcloud $max_version" + continue + fi + + echo "[INFO] $app: installed version only supports up to Nextcloud $max_version" + + if [ "$compatible_apps_fetched" != "1" ]; then + compatible_apps_fetched=1 + compatible_apps=$(curl -fsSL --max-time 30 "https://apps.nextcloud.com/api/v1/platform/${target_major}.0.0/apps.json" 2>/dev/null \ + | php -r '$d=json_decode(stream_get_contents(STDIN),true); if(is_array($d)) foreach($d as $a) echo $a["id"]."\n";') + fi + + if [ -z "$compatible_apps" ]; then + echo "[FAIL] $app: could not reach apps.nextcloud.com to check for a newer compatible release, verify manually" + ok=false + elif echo "$compatible_apps" | grep -qxF "$app"; then + echo "[WARN] $app: apps.nextcloud.com has a release that supports $target_major. It may not update until Nextcloud is upgraded, occ upgrade will try to update it automatically" + else + echo "[FAIL] $app: no apps.nextcloud.com release supports $target_major yet, it will be disabled during the upgrade" + ok=false + fi + done + + echo + if [ "$ok" = true ]; then + echo "=== READY: no blocking issues found for upgrade to major $target_major ===" + return 0 + else + echo "=== NOT READY: resolve the [FAIL] items above before running the upgrade ===" + return 1 + fi +} diff --git a/release/next b/release/next new file mode 100644 index 0000000..4c2a64c --- /dev/null +++ b/release/next @@ -0,0 +1 @@ +Added `check_major_upgrade` (`abra app cmd app check_major_upgrade`) to check whether an instance is ready to upgrade to the next Nextcloud major version.