Update docs and hub updater defaults for latest fixes

Co-Authored-By: Oz <oz-agent@warp.dev>

.hub-update.env.example

@@ -1,4 +1,5 @@
 RUN_APP_UPDATES=1
+RUN_EXPENSIVE_REPAIR=1
 STRICT_TLS=0
 ENABLE_WEB_UPDATER=1
 UPDATER_RELEASE_CHANNEL=stable

README.md

@@ -16,12 +16,21 @@ The stack now includes:
 - Production TLS provisioning using Let's Encrypt DNS-01 with Cloudflare
 - Automated TLS renewal job support (cron)
 - Nextcloud app startup fixes for Apache `ServerName` and writable Fontconfig cache
-- Persistent web-updater enablement (`upgrade-disable-web.config.php` forced to `false` on app startup)
+- Persistent web-updater enablement (`upgrade-disable-web.config.php` forced to `false`)
 - Reverse-proxy trust configuration in Nextcloud (`trusted_proxies`, `forwarded_for_headers`)
 - Nginx hardening (`server_tokens off`, stronger HSTS, hide `X-Powered-By`, TLS session hardening)
 - Brute-force protection explicitly enabled and maintenance window configured
 - Scripted Nextcloud Hub upgrade workflow: `scripts/update-nextcloud-hub.sh`
 - Automated Hub update scheduler: `scripts/setup-hub-update-cron.sh`
+- Redis service for transactional file locking and distributed cache
+- Floating app image tag enabled: `nextcloud:apache` (major upgrades supported with staged path)
+- Setup warning remediation integrated (missing indices, mimetype migrations, log-noise cleanup)
+
+## Current baseline (Apr 2026)
+- App image: `nextcloud:apache`
+- DB image: `mariadb:11.4`
+- Cache/locking: `redis:7-alpine`
+- Nextcloud version at last validation: `33.0.2`
 
 ## Prerequisites
 - Ubuntu host with Docker + Docker Compose plugin (or `docker-compose`)
@@ -45,7 +54,7 @@ cp .env.example .env
 ```
 
 ## Enable web updater (one-time verification)
-Web updater is now enabled by design for this deployment.
+Web updater is enabled by design for this deployment.
 
 Check values:
 ```bash
@@ -56,14 +65,8 @@ Expected:
 - `upgrade.disable-web: false`
 - `updater.release.channel: stable`
 
-If you need to enforce immediately without restart, run:
-```bash
-./scripts/update-nextcloud-hub.sh
-```
-This script also rewrites `config/upgrade-disable-web.config.php` inside the app container volume.
-
 ## Update Nextcloud Hub (scripted)
-Use the upgrade helper script to pull new images, apply the upgrade, run post-upgrade repairs, and validate endpoints.
+Use the upgrade helper script to pull images, apply upgrades, run repairs, and validate endpoints.
 
 Run update:
 ```bash
@@ -75,6 +78,10 @@ Optional flags:
 ```bash
 RUN_APP_UPDATES=0 ./scripts/update-nextcloud-hub.sh
 ```
+- Skip expensive repairs/mimetype migration pass:
+```bash
+RUN_EXPENSIVE_REPAIR=0 ./scripts/update-nextcloud-hub.sh
+```
 - Require strict TLS validation during smoke tests (no `-k`):
 ```bash
 STRICT_TLS=1 ./scripts/update-nextcloud-hub.sh
@@ -82,15 +89,23 @@ STRICT_TLS=1 ./scripts/update-nextcloud-hub.sh
 
 What the script does:
 - pulls latest `db`, `app`, and `web` images
-- recreates services via Compose
+- recreates services and restarts `web` to refresh upstream resolution
 - ensures web updater is enabled and release channel is configured
-- ensures maintenance mode is off before `occ upgrade` (fixes prior deadlock)
+- ensures maintenance mode is off before `occ upgrade`
 - runs `occ upgrade`
 - runs `occ app:update --all` (unless disabled)
 - runs schema and repair commands (`db:add-missing-*`, `maintenance:repair`)
+- optionally runs `maintenance:repair --include-expensive`
 - runs `occ status`, `occ setupchecks`, and `scripts/test.sh`
 
-> Recommendation: take a filesystem/database backup before major Hub upgrades.
+### Important: major upgrades are one-at-a-time
+Nextcloud only supports upgrading one major version at a time.
+
+If the floating `nextcloud:apache` tag is more than one major ahead of your installed version, do staged upgrades first, for example:
+1. `nextcloud:31-apache` → run updater script
+2. `nextcloud:32-apache` → run updater script
+3. `nextcloud:33-apache` → run updater script
+4. switch back to `nextcloud:apache`
 
 ## Automate Hub updates (cron)
 Install/update a weekly cron job (default: Sunday 02:30):
@@ -108,12 +123,25 @@ This setup script will:
 - install/refresh cron entry for `scripts/update-nextcloud-hub.sh`
 - write logs to `logs/hub-update.log`
 
-Defaults are tracked in `.hub-update.env.example`:
+Defaults tracked in `.hub-update.env.example`:
 - `RUN_APP_UPDATES=1`
+- `RUN_EXPENSIVE_REPAIR=1`
 - `STRICT_TLS=0`
 - `ENABLE_WEB_UPDATER=1`
 - `UPDATER_RELEASE_CHANNEL=stable`
 
+## Setup warning remediation notes
+The following warning-focused fixes are now part of the deployed configuration:
+- **Transactional File Locking**: Redis-backed locking enabled (`memcache.locking=Redis`)
+- **Mimetype migrations**: addressed via `maintenance:repair --include-expensive`
+- **Missing optional indices**: addressed via `occ db:add-missing-indices`
+- **AppAPI deploy daemon errors**: `app_api` disabled (not used in this deployment)
+- **Internet connectivity check log spam**: `has_internet_connection=false` set intentionally for this environment
+
+If you want AppAPI external apps later:
+- re-enable app: `docker exec --user www-data nextcloud-app php occ app:enable app_api`
+- configure a reachable deploy daemon from Settings > AppAPI
+
 ## Move Nextcloud data directory to external storage
 Use the migration helper to move existing data to a host path and switch the app to a bind mount.
 
@@ -194,29 +222,6 @@ NEW_NEXTCLOUD_PASSWORD={{NEW_NEXTCLOUD_PASSWORD}} ./scripts/reset-admin-password
 
 You can target a different username by passing it as the first argument.
 
-## Operational/security changes applied (Apr 2026)
-Applied and validated in this deployment:
-
-- `docker-compose.yml` (`app` service):
-  - startup command ensures writable `/var/cache/fontconfig`
-  - sets Apache `ServerName nxt.bhatfamily.in`
-  - sets `XDG_CACHE_HOME=/tmp/.cache`
-  - forces `config/upgrade-disable-web.config.php` to `upgrade.disable-web=false`
-- `nginx/nginx.conf`:
-  - `server_tokens off`
-  - HSTS set to `max-age=63072000; includeSubDomains; preload`
-  - `proxy_hide_header X-Powered-By`
-  - `ssl_session_cache`, `ssl_session_timeout`, `ssl_session_tickets off`
-- Nextcloud `occ` settings:
-  - `trusted_proxies` configured to Docker network subnet
-  - `forwarded_for_headers` set to `HTTP_X_FORWARDED_FOR`
-  - `auth.bruteforce.protection.enabled=true`
-  - `maintenance_window_start=1`
-  - `updater.release.channel=stable`
-  - `weather_status` app disabled to remove repeated PHP warning noise
-- Host security hygiene:
-  - `.env` permission reduced to `600`
-
 ## Useful commands
 Start/update containers:
 ```bash
@@ -237,5 +242,6 @@ Stop and remove containers/volumes:
 
 ## Security notes
 - `.env`, `.tls-renewal.env`, `.hub-update.env`, and runtime cert material under `nginx/ssl` are intentionally ignored by Git.
+- `backups/` is ignored and used for local database/log snapshots before risky changes.
 - Keep `.env` mode restricted (`chmod 600 .env`).
 - If secrets were ever committed earlier, rotate them.

scripts/setup-hub-update-cron.sh

@@ -19,6 +19,7 @@ if [ -f "${HUB_ENV_FILE}" ]; then
 fi
 
 RUN_APP_UPDATES="${RUN_APP_UPDATES:-1}"
+RUN_EXPENSIVE_REPAIR="${RUN_EXPENSIVE_REPAIR:-1}"
 STRICT_TLS="${STRICT_TLS:-0}"
 ENABLE_WEB_UPDATER="${ENABLE_WEB_UPDATER:-1}"
 UPDATER_RELEASE_CHANNEL="${UPDATER_RELEASE_CHANNEL:-stable}"
@@ -28,6 +29,7 @@ chmod 700 "${LOG_DIR}"
 
 cat > "${HUB_ENV_FILE}" <<ENVFILE
 RUN_APP_UPDATES=${RUN_APP_UPDATES}
+RUN_EXPENSIVE_REPAIR=${RUN_EXPENSIVE_REPAIR}
 STRICT_TLS=${STRICT_TLS}
 ENABLE_WEB_UPDATER=${ENABLE_WEB_UPDATER}
 UPDATER_RELEASE_CHANNEL=${UPDATER_RELEASE_CHANNEL}

scripts/update-nextcloud-hub.sh

@@ -9,6 +9,7 @@ REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 COMPOSE_FILE="${REPO_DIR}/docker-compose.yml"
 APP_CONTAINER="${NEXTCLOUD_APP_CONTAINER:-nextcloud-app}"
 RUN_APP_UPDATES="${RUN_APP_UPDATES:-1}"
+RUN_EXPENSIVE_REPAIR="${RUN_EXPENSIVE_REPAIR:-1}"
 STRICT_TLS="${STRICT_TLS:-0}"
 ENABLE_WEB_UPDATER="${ENABLE_WEB_UPDATER:-1}"
 UPDATER_RELEASE_CHANNEL="${UPDATER_RELEASE_CHANNEL:-stable}"
@@ -126,6 +127,13 @@ occ_cmd db:add-missing-primary-keys || true
 echo "==> Running maintenance repair"
 occ_cmd maintenance:repair
 
+if [ "${RUN_EXPENSIVE_REPAIR}" = "1" ]; then
+  echo "==> Running expensive maintenance repair tasks (mimetype migrations, deep cleanups)"
+  occ_cmd maintenance:repair --include-expensive
+else
+  echo "==> Skipping expensive maintenance repair (RUN_EXPENSIVE_REPAIR=${RUN_EXPENSIVE_REPAIR})"
+fi
+
 echo "==> Running post-update checks"
 occ_cmd status
 occ_cmd setupchecks || true