diff --git a/.wiki/concepts/admin-infra-project.md b/.wiki/concepts/admin-infra-project.md new file mode 100644 index 0000000..d1291d8 --- /dev/null +++ b/.wiki/concepts/admin-infra-project.md @@ -0,0 +1,203 @@ +--- +date: '2026-05-21' +source: .workshop/.brainstorm/admin-infra-project.md +status: promoted +type: design +title: admin-infra-project +ingested_at: '2026-05-21T10:21:27.239Z' +ingested_by: OpeItcLoc03@DESKTOP-NSEF0UK +source_project: OpeItcLoc03/workshop +--- +## Summary + +Design + execution plan for the `OpeItcLoc03/admin` infrastructure project — extracted from `MoreThenCms` catch-all that accumulated admin/recovery content during the 2026-05-18 SMR-cascade incident when git was unavailable. This document is the canonical design context for the migration tasks in `.tasks/STATUS.md`. + +## Context + +**Incident:** 2026-05-18 WD40EFAX SMR-cascade in RAID 5 → dead Synology DSM. Git was hosted on the dead NAS. Several days gitless; client production rebuilt ad-hoc. + +**Current state (as of 2026-05-21):** +- Git restored on VDS Rusonyx — `git.kzntsv.site` (gitea 1.25.5). See `concepts/vds-kzntsv` (after migration). +- Client production temporary scheme: OpenWRT NAT → traefik on Windows host → IIS on host (attempt-2 migration closed 2026-05-21 36h soak). +- All 8/8 client sites green via public HTTPS chain. +- Known open issue: `maljarka.tandemmebel.ru` 502 in HTTPS-mode — CMS-side, stays in `MoreThenCms`. + +**Why admin:** `MoreThenCms` became a catch-all because git was down during the incident — admin/infra content (recovery, VDS bootstrap, traefik quirks, fault-tolerance roadmap placeholder) ended up mixed with CMS-domain content. Decoupling now. + +## Identity + +- **Gitea:** `OpeItcLoc03/admin` +- **Local:** `~/projects/.admin/` +- **Default branch:** `master` +- **Discipline overrides:** master-only, commit-freely, push-by-permission (per `.workshop` pattern) +- **CLAUDE.md profile:** `use superpowers`, `use project wiki`, `use task management system`, `check across all projects`, `pull remote before work`, `follow project discipline`, `delegate to interns when allowed`, `recommend, don't menu`, `we're on Windows`, `talk like a caveman`. **Dropped vs MoreThenCms:** `follow tdd-criteria` (admin work is mostly non-TDD-shape: scripts, runbooks, configs; tdd-criteria carve-outs already cover this). + +## Scope / mission + +`admin` — single home for the full infra agenda: + +1. **Current ops / incidents** — vds-ops, backup runs, traefik-quirks +2. **Migration work** — IIS-on-host, DB-park, LE certs for DBs, DNS-01 for acme +3. **Fault-tolerance roadmap** — placeholder `future-resilient-architecture-goals` expands here into a real plan (RTO/RPO, 3-2-1, multi-host, monitoring, runbooks) +4. **Coordination of infra repos** — `vds-ops-mcp`, `synology-ops-mcp`, `agenda`, `projects-meta-mcp`, `projects-wiki`, `claude-skills` stay as their own repos; admin tracks tasks/decisions about them + +**Out of scope:** CMS-domain (stays in `MoreThenCms`), business projects (books, pilonuxt, etc.), workshop boss-zone. + +## Content inventory — what migrates from MoreThenCms + +### Stays in MoreThenCms (CMS-domain) + +**Tasks:** +- `cms-admin-assets-root-folders-seed`, `cms-port-leak-fix`, `traefik-maljarka-502-bug` (CMS-side diagnosis), `cms-maljarka-https-mode-bug-fix` (open follow-up) + +**Wiki concepts:** +- `cms-admin-assets-root-folder-seed`, `cms-server-port-leak-fix`, `cms-config-rewrite-pattern`, `cms-maljarka-https-mode-crash`, `webconfig-password-xml-escape` + +### Migrates to admin (infra) + +**Tasks (7):** +- `vds-kzntsv-bootstrap`, `vds-gc-cron`, `vds-backup-rsync-kreknin`, `vds-ntfy-push` +- `nas-recovery`, `iis-on-host-migration`, `iis-traefik-dead-routes-cleanup` + +**Wiki entities (all 6):** +- `dead-synology-diskstation`, `kreknin-synology`, `windows-recovery-host`, `snolla-recovery-vm`, `openwrt-router`, `vds-kzntsv` + +**Wiki concepts (18):** +- `wd40efax-smr-cascade`, `hyper-backup-structure-and-recovery`, `vbox-windows-stability-tuning` +- `mssql-container-data-restore` +- `traefik-on-windows-docker-desktop`, `traefik-tcp-passthrough-vs-starttls`, `traefik-file-watch-wsl2-broken` +- `docker-host-loopback-detect`, `compose-bcrypt-escape-trap` +- `portainer-2.21-admin-password-regression`, `db-tls-self-signed-via-traefik-raw-tcp` +- `rusonyx-vps-onboarding-quirks`, `registry-gc-mount-and-modify-flag`, `verdaccio-prune-semantics` +- `recovery-architecture-snapshot`, `future-resilient-architecture-goals`, `iis-migration-2026-05-19-postmortem` + +**Wiki sources (all 3):** +- `nas-recovery-session-2026-05-18`, `iis-host-migration-2026-05-19`, `vds-kzntsv-bootstrap-2026-05-20` + +### Grey-zone (resolved) + +- `iis-on-host-migration` task + `iis-host-migration-2026-05-19` source → **admin** (hosting-platform migration; CMS-side bugs surfaced by it stay in MoreThenCms). +- `recovery-architecture-snapshot` → **admin** (full request flow including admin layer; MoreThenCms doesn't need its own — uses breadcrumb to admin). + +## Migration mechanics — git subtree split for per-file history + +**Goal:** preserve per-file git history for admin-domain files. CMS-only files appear in admin's git history as imported-then-deleted (acceptable noise, explained in cleanup commit message). + +**Recipe (executed in dedicated session — see task list):** + +1. **Pre-step (DONE 2026-05-21):** `OpeItcLoc03/admin` repo created on Gitea (master, auto-init). Local clone `~/projects/.admin/`. Bootstrap commit added `CLAUDE.md`, `.gitignore` (with `!.wiki/` `!.tasks/` to override global ignore), `.tasks/STATUS.md` (header only), `.wiki/` skeleton (`CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, empty `entities/`, `concepts/`, `packages/`, `sources/`). + +2. **Subtree-split in MoreThenCms** — 4 history-extraction branches: + + ```powershell + cd ~/projects/MoreThenCms + git subtree split --prefix=.wiki/entities -b split-wiki-entities + git subtree split --prefix=.wiki/sources -b split-wiki-sources + git subtree split --prefix=.wiki/concepts -b split-wiki-concepts + git subtree split --prefix=.tasks -b split-tasks + ``` + +3. **Subtree-add into admin** — clean targets work straight, populated targets need merge approach. + + `.wiki/entities/` and `.wiki/sources/` are empty (only `.gitkeep`) — `git subtree add` works after removing `.gitkeep`: + + ```powershell + cd ~/projects/.admin + git remote add morecms ~/projects/MoreThenCms + git fetch morecms + git rm .wiki/entities/.gitkeep .wiki/sources/.gitkeep + git commit -m "prep: clear gitkeep before subtree import" + git subtree add --prefix=.wiki/entities morecms/split-wiki-entities + git subtree add --prefix=.wiki/sources morecms/split-wiki-sources + ``` + + `.wiki/concepts/` already contains `admin-infra-project.md` (this doc, ingested at promote time) and `.gitkeep`. `.tasks/` already contains `STATUS.md`. `git subtree add` requires an empty prefix → fails. Use one of: + + - **(preferred) `git read-tree --prefix=/ -u ` then `git commit`** — merges trees, preserves history via subsequent `git log --follow`. Conflict resolution is manual but the design doc / STATUS.md don't overlap by filename with imported files. + - **(alt) Temp-prefix dance:** `git subtree add --prefix=.tmp-concepts ` then `git mv .tmp-concepts/* .wiki/concepts/`, then `git rm -r .tmp-concepts`. Two commits, but preserves history. + +4. **admin cleanup commit** — remove CMS-only files that came in via mixed-dir splits: + + ```powershell + git rm .wiki/concepts/cms-admin-assets-root-folder-seed.md ` + .wiki/concepts/cms-config-rewrite-pattern.md ` + .wiki/concepts/cms-maljarka-https-mode-crash.md ` + .wiki/concepts/cms-server-port-leak-fix.md ` + .wiki/concepts/webconfig-password-xml-escape.md ` + .tasks/cms-admin-assets-root-folders-seed.md ` + .tasks/cms-admin-assets-root-folders-seed.inserted-rows.txt ` + .tasks/cms-maljarka-https-mode-bug-fix.md ` + .tasks/cms-port-leak-fix.md ` + .tasks/traefik-maljarka-502-bug.md + git commit -m "cleanup: drop CMS files imported via subtree (they stay in MoreThenCms)" + ``` + +5. **admin STATUS.md merge** — imported `.tasks/STATUS.md` from MoreThenCms contains the full mixed history. Merge with admin's stub header + new live tasks (created via promote). Manual edit; commit as `tasks: merge imported MoreThenCms history with admin live agenda`. + +6. **admin index.md regeneration** — refresh `.wiki/index.md` to reflect new entities/concepts/sources catalog. + +7. **admin push to Gitea** — `git push origin master`. + +8. **MoreThenCms cleanup commit** — remove migrated files: + + ```powershell + cd ~/projects/MoreThenCms + git rm .wiki/entities/* .wiki/sources/* ` + .wiki/concepts/{wd40efax-smr-cascade,hyper-backup-structure-and-recovery,vbox-windows-stability-tuning,mssql-container-data-restore,traefik-on-windows-docker-desktop,traefik-tcp-passthrough-vs-starttls,traefik-file-watch-wsl2-broken,docker-host-loopback-detect,compose-bcrypt-escape-trap,portainer-2.21-admin-password-regression,db-tls-self-signed-via-traefik-raw-tcp,rusonyx-vps-onboarding-quirks,registry-gc-mount-and-modify-flag,verdaccio-prune-semantics,recovery-architecture-snapshot,future-resilient-architecture-goals,iis-migration-2026-05-19-postmortem}.md ` + .tasks/{vds-kzntsv-bootstrap,vds-gc-cron,vds-backup-rsync-kreknin,vds-ntfy-push,nas-recovery,iis-on-host-migration,iis-traefik-dead-routes-cleanup}.md + # Edit STATUS.md to remove migrated entries, keep CMS ones + # Edit .wiki/index.md to remove migrated catalog entries + ``` + +9. **MoreThenCms breadcrumb** — add `.wiki/concepts/migrated-infra-to-admin.md`: + + ```markdown + --- + title: Infrastructure content migrated to admin project + date: 2026-05-21 + --- + + # Migration to OpeItcLoc03/admin + + NAS recovery, VDS bootstrap, IIS-on-host migration, traefik/portainer/registry quirks, fault-tolerance roadmap, and related infrastructure knowledge migrated to `OpeItcLoc03/admin` on 2026-05-21. Per-file history preserved via `git subtree split`. + + | Was here | Now here | + |---|---| + | `.wiki/entities/*` (6 files) | `OpeItcLoc03/admin:.wiki/entities/` | + | `.wiki/sources/*` (3 chronologies) | `OpeItcLoc03/admin:.wiki/sources/` | + | `.wiki/concepts/{wd40efax-smr-cascade,traefik-*,vbox-*,mssql-*,portainer-*,registry-*,verdaccio-*,db-tls-*,rusonyx-*,compose-bcrypt-*,docker-host-loopback,future-resilient-*,recovery-architecture-snapshot,iis-migration-*-postmortem}` | `OpeItcLoc03/admin:.wiki/concepts/` | + | `.tasks/{vds-*,nas-recovery,iis-on-host-migration,iis-traefik-dead-routes-cleanup}.md` | `OpeItcLoc03/admin:.tasks/` | + + ## What stays here (CMS-domain) + + - `.wiki/concepts/cms-*.md` (4 files) + `webconfig-password-xml-escape.md` + - `.tasks/cms-*.md` + `traefik-maljarka-502-bug.md` + ``` + +10. **MoreThenCms push.** + +11. **Sync + verify:** + - `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` + - `mcp__projects-meta__tasks_aggregate project: "OpeItcLoc03/admin"` returns imported tasks + - `mcp__projects-meta__knowledge_search query: "vds bootstrap" domain: "all"` finds admin's wiki content (after `knowledge_ingest` cycles run or via gitea-side index) + +## Initial admin agenda (post-migration live tasks) + +**`[resilience-roadmap-design]`** — pre-impl design task. Expand `concepts/future-resilient-architecture-goals.md` placeholder into a real roadmap: RTO/RPO targets, 3-2-1 backup, multi-host options, monitoring stack, runbooks. Natural entry point for the global goal stated by the user: "build a fault-tolerant solution so the 2026-05-18 incident does not repeat." + +**`[secrets-out-of-common]`** — stage 1 of secret-management fix. Move `~/projects/.common/secrets/` → `~/.config/projects-secrets/` (outside git-tree). Consumers (`interns-mcp`, `projects-meta-mcp`, `mcpServers.*` configs in `~/.claude.json`) accept absolute paths / env-override — only source path changes. **Why:** `.common/` is a git-tracked tree; secrets in it = leak risk via `git add .` / disabled gitignore + Synology Hyper Backup tarballs the tree including secrets + IDE/LSP indexing sees plaintext. + +**`[secrets-manager-adopt]`** (blocked by `[secrets-out-of-common]`) — stage 2: adopt `pass` (gpg password-store, Windows port via MSYS2/Scoop) or Bitwarden CLI. **Recommend `pass`** — git-syncable encrypted blobs, per-user gpg, no cloud dependency. **Why:** even after stage 1 secrets are plaintext in `~/.config/`; `pass` adds encrypted-at-rest + cross-machine sync via private Gitea repo with encrypted files. + +## Tools / skills audit (deliberate non-decisions) + +- **Admin-specific skills/tools** — not needed yet. Existing skills cover the work: `using-vds-ops`, `using-synology-ops`, `using-wiki`, `using-tasks`, `using-projects-meta`, `project-discipline`, `using-markitdown`, `tdd-criteria` (for scripts where TDD-shape applies). +- **If repeating patterns emerge** (runbook format, postmortem template, cert-renewal-checklist) — they become **global** skills in `claude-skills`, not admin-tagged. "admin-only" in a skill name is an anti-pattern; skills trigger on context, not project. +- **Known tool gap:** write-capable `vds-ops-mcp` (currently `POST=0` in tecnativa proxy). Separate future task, not blocking admin's bootstrap. + +## Source / archive + +- **Brainstorm trace:** `~/projects/.workshop/.archive/2026-05-21-admin-infra-project.md` (this design's rationale, what was rejected, anti-patterns) +- **Promotion date:** 2026-05-21 +- **Pre-impl bootstrap task:** `[admin-infra-project-pointers]` (seeds `.wiki/CLAUDE.md` Domain conventions with pointers to this concept + workshop archive) +- **Review umbrella:** `[admin-infra-project-review]` (blocked by all impl tasks; reviewer is not the implementer)