From eec1228dc8e64182074b8786bb529809f94c1527 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sun, 13 Sep 2026 09:40:22 +0200 Subject: [PATCH] MariaDB finishes its own conversion: MARIADB_AUTO_UPGRADE=1 on the four db services (R-459) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS --- REUSE.md | 1 + templates/bookstack/docker-compose.yml | 5 +++++ templates/kimai/docker-compose.yml | 5 +++++ templates/nextcloud/docker-compose.yml | 5 +++++ templates/romm/docker-compose.yml | 5 +++++ 5 files changed, 21 insertions(+) diff --git a/REUSE.md b/REUSE.md index af5833e..b74a6bb 100644 --- a/REUSE.md +++ b/REUSE.md @@ -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',),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 -d `; mariadb: `healthcheck.sh --connect --innodb_initialized`; redis: `redis-cli ping`. App container gets `depends_on: : 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_.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 + `-internal` for DBs, Traefik labels with ``Host(`${SUBDOMAIN}.${DOMAIN}`)``, named volumes for DB/config (NVMe), `${HDD_PATH}/appdata//...` 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. | diff --git a/templates/bookstack/docker-compose.yml b/templates/bookstack/docker-compose.yml index b3e7f0e..56aa373 100644 --- a/templates/bookstack/docker-compose.yml +++ b/templates/bookstack/docker-compose.yml @@ -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: diff --git a/templates/kimai/docker-compose.yml b/templates/kimai/docker-compose.yml index ad3c9e1..df443e5 100644 --- a/templates/kimai/docker-compose.yml +++ b/templates/kimai/docker-compose.yml @@ -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: diff --git a/templates/nextcloud/docker-compose.yml b/templates/nextcloud/docker-compose.yml index d197d9c..a823d69 100644 --- a/templates/nextcloud/docker-compose.yml +++ b/templates/nextcloud/docker-compose.yml @@ -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: diff --git a/templates/romm/docker-compose.yml b/templates/romm/docker-compose.yml index f3634b9..6e2e337 100644 --- a/templates/romm/docker-compose.yml +++ b/templates/romm/docker-compose.yml @@ -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: