Architectural choices made during the cleanup project, with date and reasoning.
- Decision: Every page of a given type follows a fixed section order
rendered from a single template + a structured data file.
- Why: Inconsistent section order across pages was the cluttered-feeling
problem with the BookStack era. Templates make every VM page, host page,
service page, etc. look the same — so readers always know where the
information is. Empty subsections are omitted to avoid placeholder noise.
- How:
tools/wikijs_data.py is the single source of truth for structured
pages. tools/wikijs_templates.py defines the renderers. tools/seed-wikijs-v2.py
upserts. Re-run after any edit to wikijs_data.py.
- Decision: Replace BookStack with Wiki.js v2.5.307 as the project wiki.
- Why: BookStack's shelf -> book -> chapter -> page hierarchy became
cluttered at ~90 pages. Wiki.js's tree navigation is cleaner for technical
documentation and supports markdown natively.
- DB choice: Reuse existing
postgres_production (PG 18) on VM-SL-00
instead of standing up a new Postgres sidecar.
- Auth: Authentik OIDC + Wiki.js group
grp-wiki-admin (matches Authentik
group of same name) for admin role mapping.
- Cutover style: Hot — BookStack stopped, archived, replaced. PBS image
- on-disk archive at
/opt/wiki-bookstack-archive/ are the rollback paths.
- Image:
requarks/wiki:2.5.307 (TODO digest pin).
- Decision: Single Tdarr flow with
checkNodeHardwareEncoder plugin
branching: nodes with NVENC use hevc_nvenc p7 CQ22, CPU-only nodes
fall back to libx265 slow CRF22.
- Why: Allows both
tdarr-node-vm-sl-22 and the future tdarr-node-pc-rtx3060
to participate in encoding without duplicating flows or libraries.
- Decision: One CPU worker on the Linux Tdarr node, not four.
- Why:
libx265 -preset slow is multi-threaded and saturates available
cores. Four parallel workers contend for the same CPUs, producing identical
total throughput but 4× longer latency per file. Load average had hit 24
on an 8-vCPU VM, noisy for the Proxmox host.
- Decision: Document the v2.70 library-config field names that aren't
the obvious ones, in Services / Tdarr / v2.70 API gotchas.
- Why: Several library fields are misleadingly named or used internally
(containerFilter instead of allowedContainers, foldersToIgnore is a
comma-separated string and not an array, decisionMaker.settingsFlows
drives Flows-vs-Classic). UI-created libraries set them correctly;
API-created libraries do not.
- Wiki Phase 1 stack (now superseded): BookStack + MariaDB sidecar,
Authentik OIDC, no backups yet, /opt/wiki/. See Archive
for the original decision page.
- Naming convention:
VM-{SITE}-{ROLE}-{NN} (SL/SW/RP/IO/PB),
/opt/{service}/, grp-{service}-{role}. Applies to NEW artifacts only.
- Tdarr scope: movies + series only. Family photos (Immich) strictly
off-limits for any re-encoding pipeline.
- Hard constraints: VM-only architecture; HA via extra hardware out of
scope; backups at VM-image level via PBS; SPoFs (single pfSense per site,
single VPN tunnel, single AD DC, single NAS) are accepted cost trade-offs.
- 2026-05-01 — Postgres 17.6 zentral auf
vm-rz-db-01 (centralized DB strategy).
- 2026-05-01 — Wiki.js / GitLab / Nextcloud migriert auf
vm-rz-svc-prod-01 (single SVC tier).
- 2026-05-02 — ACME-Challenge HTTP-01 auf beiden EDGE-VMs (locked, siehe
policies/acme-challenge).
- 2026-05-02 — HM IP allocation v2 mit PROD/STAGE-Suffix und HM-DC-01 auf .10 (locked, siehe
policies/ip-allocation-hm).
- 2026-05-02 — Heimdall ersetzt durch Homepage auf
vm-hm-svc-prod-01.
- 2026-05-02 — n8n decommissioned (Route gestoppt im vm-sl-21-Cutover).
- 2026-05-03 — DC-Migration RZ → HM (in flight: ESXi-Snapshot blockiert Proxmox-Import).
- 2026-05-03 — Databasement live + GFS-Schedules auf
vm-hm-backup-01.