MariaDB finishes its own conversion: MARIADB_AUTO_UPGRADE=1 on the four db services (R-459)

bookstack-db, kimai-db, nextcloud-db, romm-db each gain `MARIADB_AUTO_UPGRADE=1` in the db service's environment list. Operator ruling 2026-09-13 on the measurement in felhom.eu/documentation/audits/SPIKE-r459-mariadb-upgrade-2026-09-06.md: an unconverted datadir is stable but never heals; the conversion costs ~7 s and the engine backs its system tables up first. MARIADB_DISABLE_UPGRADE_BACKUP is deliberately left UNSET — that backup is the precaution. NO `image:` line changed, so `catalog_since` does NOT move — the CLAUDE.md rule ties it to an image change and this is not one. Do not "fix" that. The setting is inert until an engine major actually moves, and none may until Slice 4 (R-448) ships — see the engine-major rule in CLAUDE.md and scripts/check-engine-major.py (next commit). The eleven PostgreSQL templates are untouched: R-463 is a different engine and a different measurement. REUSE.md: one convention row for the MariaDB sidecar env, same commit. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
2026-09-13 09:40:22 +02:00
parent b7ef0c4a09
commit eec1228dc8
5 changed files with 21 additions and 0 deletions
@@ -27,6 +27,7 @@ None — this repo is templates/config, not code. See §2/§5.
 | Docker healthcheck — Node images (no wget/curl) | `templates/rallly/docker-compose.yml` (~L49) | `test: ["CMD", "node", "-e", "require('http').get(...)"]` — used when the image lacks wget (that was rallly's actual bug). |
 | Docker healthcheck — Python images | `templates/mealie/docker-compose.yml` (~L47) | `test: ["CMD-SHELL", "python3 -c \"import socket; s=socket.create_connection(('localhost',<port>),2); s.close()\""]` (mealie, crafty-controller). tandoor/wger use `urllib.request` variants for real HTTP checks. |
 | Docker healthcheck — DB/Redis sidecars | `templates/paperless-ngx/docker-compose.yml` (~L107, L129) | postgres: `pg_isready -U <user> -d <db>`; mariadb: `healthcheck.sh --connect --innodb_initialized`; redis: `redis-cli ping`. App container gets `depends_on: <db>: condition: service_healthy`. |
+| MariaDB sidecar — `MARIADB_AUTO_UPGRADE=1` | `templates/bookstack/docker-compose.yml` (`bookstack-db` `environment:`), also kimai/nextcloud/romm | **Every `mariadb:` sidecar carries `MARIADB_AUTO_UPGRADE=1`** (operator ruling 2026-09-13, `felhom.eu/documentation/audits/SPIKE-r459-mariadb-upgrade-2026-09-06.md`). Without it a major engine move starts on the old datadir, logs that the conversion was **skipped**, and says `Check required!` on every start forever (R-459); with it the engine converts in ~7 s and backs its system tables up first (`system_mysql_backup_<ver>.sql.zst` left in the datadir). `MARIADB_DISABLE_UPGRADE_BACKUP` stays UNSET — that backup is the precaution. **Not an image change, so `catalog_since` does not move.** TRAP (R-464): the entrypoint prints `MariaDB upgrade not required` on an UNSUPPORTED downgrade too — ask `mariadb-upgrade --check-if-upgrade-is-needed` (exit 0 = needed, 1 = not), never the log line. PostgreSQL sidecars have NO equivalent (the image runs no `pg_upgrade`, R-463). **Until Slice 4 (R-448) ships, no template may move a `mariadb:`/`postgres:` pin across a MAJOR** — `scripts/check-engine-major.py` refuses it in the pre-push hook. |
 | Memory convention | `templates/paperless-ngx/docker-compose.yml` (~L71) + `.felhom.yml resources:` | EVERY service has `deploy.resources.limits.memory` (compose is the enforcement). NO `reservations` anywhere. `.felhom.yml mem_limit` = SUM of all containers' limits (see paperless header comment: 768+256+128=1152M); `mem_request` = expected steady-state usage, display-only. |
 | Compose file skeleton | `templates/paperless-ngx/docker-compose.yml` (header) | Header comment (app, domain, DB type, RAM math, Pi), `restart: unless-stopped`, `TZ=Europe/Budapest`, explicit `container_name`, `traefik-public` external network + `<app>-internal` for DBs, Traefik labels with ``Host(`${SUBDOMAIN}.${DOMAIN}`)``, named volumes for DB/config (NVMe), `${HDD_PATH}/appdata/<app>/...` for bulk data, `${USERDATA_PATH}/...` for customer-browsable content. |
 | App-email (SMTP shim) opt-in | `templates/vaultwarden/.felhom.yml` (`smtp_mapping:`) + README.md §smtp_mapping | `smtp_mapping` maps shim host/port/security/from to the app's own env names; compose MUST reference the mapped `${VAR:-}` keys with empty defaults. STARTTLS if the app can accept self-signed certs, else `security_value: "NONE"` plaintext (or the :2526 plaintext listener for STARTTLS-insistent clients — see calcom/nextcloud). TRAP: an image that treats defined-but-EMPTY mail vars as "set" (vaultwarden — campaign F1 2026-07-06) needs its own enable-flag gated `false` in compose and flipped `"true"` via `smtp_mapping.extra`; boot-prove a fresh email-off deploy for every new smtp-mapped app. |
@@ -60,6 +60,11 @@ services:
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - TZ=Europe/Budapest
+      # MARIADB_AUTO_UPGRADE: on a MAJOR engine move the engine converts its own datadir (~7 s on a
+      # small DB, backs its system tables up first). Operator ruling 2026-09-13 on
+      # felhom.eu/documentation/audits/SPIKE-r459-mariadb-upgrade-2026-09-06.md. Inert until a
+      # major moves — and none may, until Slice 4 (R-448) ships: see CLAUDE.md, engine-major rule.
+      - MARIADB_AUTO_UPGRADE=1
    volumes:
      - bookstack_db_data:/var/lib/mysql
    networks:
@@ -55,6 +55,11 @@ services:
      - MYSQL_USER=kimai
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - TZ=Europe/Budapest
+      # MARIADB_AUTO_UPGRADE: on a MAJOR engine move the engine converts its own datadir (~7 s on a
+      # small DB, backs its system tables up first). Operator ruling 2026-09-13 on
+      # felhom.eu/documentation/audits/SPIKE-r459-mariadb-upgrade-2026-09-06.md. Inert until a
+      # major moves — and none may, until Slice 4 (R-448) ships: see CLAUDE.md, engine-major rule.
+      - MARIADB_AUTO_UPGRADE=1
    volumes:
      - kimai_db_data:/var/lib/mysql
    networks:
@@ -79,6 +79,11 @@ services:
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - TZ=Europe/Budapest
+      # MARIADB_AUTO_UPGRADE: on a MAJOR engine move the engine converts its own datadir (~7 s on a
+      # small DB, backs its system tables up first). Operator ruling 2026-09-13 on
+      # felhom.eu/documentation/audits/SPIKE-r459-mariadb-upgrade-2026-09-06.md. Inert until a
+      # major moves — and none may, until Slice 4 (R-448) ships: see CLAUDE.md, engine-major rule.
+      - MARIADB_AUTO_UPGRADE=1
    volumes:
      - nextcloud_db_data:/var/lib/mysql
    networks:
@@ -97,6 +97,11 @@ services:
      - MYSQL_USER=romm
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - TZ=Europe/Budapest
+      # MARIADB_AUTO_UPGRADE: on a MAJOR engine move the engine converts its own datadir (~7 s on a
+      # small DB, backs its system tables up first). Operator ruling 2026-09-13 on
+      # felhom.eu/documentation/audits/SPIKE-r459-mariadb-upgrade-2026-09-06.md. Inert until a
+      # major moves — and none may, until Slice 4 (R-448) ships: see CLAUDE.md, engine-major rule.
+      - MARIADB_AUTO_UPGRADE=1
    volumes:
      - romm_db_data:/var/lib/mysql
    networks: