From 68bab888db736f4889810288086aa54f8602d8cc Mon Sep 17 00:00:00 2001 From: Fizzlepoof Date: Tue, 26 May 2026 00:38:56 +0000 Subject: [PATCH] media: stage dedicated RomM MariaDB target --- docs/planning/SERENITY_CLEANUP_WAVE_1.md | 52 ++++++++++++++++++++++-- media/.env.example | 3 +- media/docker-compose.yaml | 20 +++++++++ 3 files changed, 70 insertions(+), 5 deletions(-) diff --git a/docs/planning/SERENITY_CLEANUP_WAVE_1.md b/docs/planning/SERENITY_CLEANUP_WAVE_1.md index 73980ad..d129190 100644 --- a/docs/planning/SERENITY_CLEANUP_WAVE_1.md +++ b/docs/planning/SERENITY_CLEANUP_WAVE_1.md @@ -327,8 +327,9 @@ Chosen target layout (2026-05-25): - place both services in the PD `media` stack so they follow the same steady-state placement already documented for PD media/library apps - attach both services to: - `media-net` for local app adjacency - - `ix-databases_shared-databases` for shared DB access - `pangolin` for internal ingress / public exposure +- attach only GameVault to `ix-databases_shared-databases` because it keeps using PD `shared-postgres` +- keep RomM on `media-net` + `pangolin`; its database will be a dedicated sibling service on `media-net`, not a shared DB consumer - preserve the current host ports on PD because live checks showed them free there: - GameVault: `8785:8080` - RomM: `8457:8080` @@ -358,9 +359,11 @@ Chosen database layout: - GameVault -> PD `shared-postgres` on `ix-databases_shared-databases` - target DB: `gamevault` - target DB user: `gamevault` -- RomM -> PD `shared-mariadb` on `ix-databases_shared-databases` +- RomM -> dedicated PD `romm-db` service on `media-net` + - target image pin: `mariadb:12.2` - target DB: `romm` - target DB user: `romm` + - target data path: `/mnt/docker-ssd/docker/appdata/romm-db/mysql` Routing/proxy notes to preserve during implementation: - RomM upstream docs call out reverse-proxy sensitivity; keep websocket support intact when the route is moved behind PD Traefik @@ -369,7 +372,7 @@ Routing/proxy notes to preserve during implementation: ### Card D2 — stage PD database targets for the wave Definition of done: - GameVault target DB/user created on PD shared-postgres or explicit exception documented -- RomM target DB/user created on PD shared-mariadb or explicit exception documented +- RomM target DB/user created on the chosen PD MariaDB target or explicit exception documented - connection details verified from the future PD app network context - migration rollback notes captured before any source export @@ -385,6 +388,8 @@ Execution notes (2026-05-25): - pre-change backup of PD media env: `/mnt/docker-ssd/docker/compose/media/.env.pre-serenity-wave2-d2-20260525-182938` - if D3/D4 later uncover an issue, keep the staged DBs unused, restore the prior media `.env` if needed, and rotate/drop the staged users before re-attempting - no Serenity source data was touched yet in D2; this card only prepared empty PD landing zones +- note after D3b: + - the staged shared-mariadb `romm` target is now superseded by the dedicated `romm-db` plan and should not be used for RomM cutover ### Card D3 — export and validate Serenity source databases Definition of done: @@ -414,7 +419,46 @@ Execution notes (2026-05-25): - treat this as a compatibility / target-selection issue, not a dump-corruption issue; the dump itself is populated and preserved in backup storage - net result: - D3 is complete for GameVault - - D3 is only partially complete for RomM until the MariaDB target strategy is revised and the restore path is proven + - D3 export validation is complete for RomM, but the original PD shared-mariadb landing target is rejected + +### Card D3b — resolve RomM PD database target compatibility +Decision: +- do not upgrade PD `shared-mariadb` just to fit RomM +- keep PD `shared-mariadb` on its current conservative shared-infra track unless a separate approved maintenance change is planned for all consumers +- provision a dedicated PD MariaDB target for RomM instead + +Evidence behind the decision: +- the RomM source dump repeatedly uses reused foreign-key names such as `CONSTRAINT \`1\`` and `CONSTRAINT \`2\`` across multiple tables +- MariaDB docs state that foreign-key names must be unique per database before MariaDB 12.1, and only become reusable across tables in MariaDB 12.1+ +- Serenity `MariaDB-Official` is MariaDB 12.2.2, which explains why the source schema can exist there +- PD `shared-mariadb` is MariaDB 11.4.11, where the same dump fails with `errno: 121` while creating `device_save_sync` +- the PD databases stack currently provisions MariaDB specifically for Uptime Kuma via `databases/initdb-mariadb/01-create-uptime-kuma-db.sh`; there is no evidence in repo or live stack layout that shared-mariadb was intentionally upgraded or validated as a broad multi-app MariaDB landing zone +- RomM's own setup docs commonly show a dedicated MariaDB container and even call out compatibility-conscious MariaDB version choices in example guides + +Operational recommendation: +- create a dedicated PD MariaDB service for RomM, isolated from `shared-mariadb` +- pin that dedicated service to a MariaDB 12.x line compatible with the Serenity source behavior unless RomM docs or release notes later justify a different pin +- attach PD RomM only to its own DB service plus the networks it already needs for ingress/library access +- leave `shared-mariadb` untouched for now to avoid coupling the RomM migration to a shared-database major-version change and validation cycle + +Definition of done for D3b: +- dedicated PD MariaDB target for RomM is chosen and documented +- target image/version pin recorded +- restore path is re-tested successfully against that dedicated target before RomM cutover proceeds + +Execution notes (2026-05-26): +- restore-path proof was executed on PD using an isolated test container pinned to `mariadb:12.2` +- test target details: + - container: `romm-db-d3b-test` + - image/runtime version: `mariadb:12.2` / `12.2.2-MariaDB` + - data path: `/mnt/docker-ssd/docker/appdata/romm-db-d3b-test/mysql` +- the preserved Serenity RomM dump `/home/fizzlepoof/serenity-wave2-d3-work/20260525-184736-serenity-romm.sql` imported cleanly into the 12.2 target on PD +- post-import verification on the PD test target returned: + - `20` tables in schema `romm` + - approximately `10.42 MB` logical table+index footprint +- result: + - the compatibility blocker is resolved for a dedicated MariaDB 12.2 target + - RomM should proceed against dedicated `romm-db`, not `shared-mariadb` ### Card D4 — sync appdata for GameVault and RomM to PD staging paths Definition of done: diff --git a/media/.env.example b/media/.env.example index be136c9..a0dbf3f 100644 --- a/media/.env.example +++ b/media/.env.example @@ -18,7 +18,8 @@ GAMEVAULT_DB_NAME=gamevault GAMEVAULT_DB_USER=gamevault GAMEVAULT_DB_PASS=changeme -# RomM MariaDB target on shared-mariadb +# RomM dedicated MariaDB target on the PD media stack +ROMM_DB_ROOT_PASSWORD=changeme ROMM_DB_NAME=romm ROMM_DB_USER=romm ROMM_DB_PASS=changeme diff --git a/media/docker-compose.yaml b/media/docker-compose.yaml index f494c5c..0ea0b40 100644 --- a/media/docker-compose.yaml +++ b/media/docker-compose.yaml @@ -8,6 +8,26 @@ networks: services: + romm-db: + container_name: romm-db + image: mariadb:12.2 + restart: unless-stopped + networks: + - media-net + environment: + MARIADB_ROOT_PASSWORD: ${ROMM_DB_ROOT_PASSWORD} + MARIADB_DATABASE: ${ROMM_DB_NAME} + MARIADB_USER: ${ROMM_DB_USER} + MARIADB_PASSWORD: ${ROMM_DB_PASS} + volumes: + - /mnt/docker-ssd/docker/appdata/romm-db/mysql:/var/lib/mysql + healthcheck: + test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"] + interval: 30s + timeout: 10s + retries: 5 + start_period: 30s + plex: container_name: ix-plex-plex-1 image: lscr.io/linuxserver/plex:latest