Etappe 76: Ein Installer, der die Fallen kennt — und ein Release, das ankommt

v0.1.70 wurde getaggt und nie veröffentlicht. Der Release-Job ist an seinem
eigenen Guard gescheitert ("CHANGELOG must have a section for this version"),
korrekt, aber hinter dem Tag: GHCR blieb auf 0.1.69, `helm install` löste brav
die neueste *veröffentlichte* Version auf, und der Operator lief auf einer
frischen VM in genau den Bug, den 0.1.70 behebt. Gemeldet hatte ich es als
ausgeliefert — belegt mit lokalem Cluster, Pod-Logs, Revision 73. Alles wahr,
alles auf der falschen Seite der Veröffentlichungsgrenze.

Sein Terminal, vier Fehlschläge, keiner davon in MatrixCtrl:

  1. Kubernetes cluster unreachable: localhost:8080   → KUBECONFIG nicht gesetzt
  2. "kept due to the resource policy"                → Neuinstallation auf alter DB
  3. admin-password leer                              → 0.1.70 nie veröffentlicht
  4. got: %E2%80%A6                                   → README-Kommando mit echtem "…"

Alle vier waren dokumentiert. Dokumentation zum Zeitpunkt des Fehlers hilft nur,
wenn man weiß, wonach man sucht — eine Meldung über Port 8080 schickt niemanden
in einen Abschnitt über Kubeconfig-Pfade.

scripts/install.sh: install · uninstall · password · status. Prüft der Reihe
nach genau das, was hier schiefging, und sagt bei jedem Punkt einen Satz statt
eines Exit-Codes. Fragt Hostname und TLS-Terminierung aus (cert-manager /
Cloudflare Full / Cloudflare Flexible / kein TLS — vier Kombinationen aus
entrypoint+tls+certIssuer, die man einzeln raten kann und dann eine Seite hat,
die halb funktioniert). Endet nicht bei "deployed", sondern bei URL, Benutzer,
Passwort und DNS-Record.

Die behaltenen Volumes sind richtig so — eine Datenbank an einen Vertipper zu
verlieren wäre schlimmer. Nur ihre Folge stand nirgends: sie machen die nächste
"frische Installation" zu einem Upgrade auf altem Bestand, ohne neues Passwort.
Das Skript erkennt sie und fragt; Löschen verlangt ein getipptes "delete",
--yes deckt es bewusst nicht ab.

Zwei Guards in `make check`, beide vor dem Tag statt danach:
  check-changelog.sh  — der CI-Guard, der 0.1.70 versenkt hat
  check-commands.sh   — kein "…" in einem Shell-Block, den jemand ausführen soll

0.1.70 wird nicht nachgezogen: der Tag ist öffentlich, veröffentlicht wurde
darunter nichts, und eine Lücke ist ein ehrlicheres Protokoll als ein
verschobener Tag.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QXXVNHRBuPjPJbo6L5eg3z

Author: BxnnyG

CHANGELOG.md

@@ -15,6 +15,58 @@ matching image, so a version identifies one exact pair
 
 ## [Unreleased]
 
+## [0.1.71] — 2026-09-05
+
+### Added
+
+- **An installer**: `scripts/install.sh` — install, upgrade, uninstall, and read the
+  admin password back. It checks the things that actually go wrong before Helm runs:
+  a kubeconfig that is not on `$KUBECONFIG` (k3s writes a root-only one), an
+  unreachable API server, a missing ingress controller, and data left behind by a
+  previous install. Then it asks how TLS should be terminated — cert-manager,
+  Cloudflare *Full*, Cloudflare *Flexible*, or plain HTTP — and afterwards prints the
+  URL, the user, the password and the DNS record needed to reach it.
+  Run it with `bash <(curl -fsSL …/scripts/install.sh)`; prompts are read from
+  `/dev/tty`, so piping the script does not make it answer its own questions.
+- **`--delete-data`**, and a matching prompt in `uninstall`, for the volumes
+  `helm uninstall` deliberately keeps. Keeping them is right — losing a database to a
+  typo is worse — but it silently turns the next "fresh install" into an upgrade over
+  an old database, which is how an install can complete with no admin password to show
+  for it. Deleting them takes the flag or a typed confirmation; `--yes` does not
+  cover it.
+
+### Fixed
+
+- **Restoring an archive failed on the schema's own foreign keys.** The first test to
+  take a real archive from a real database and put it back found three defects in ten
+  seconds, after six releases of green unit tests: rows were inserted children-first,
+  each table was truncated separately (which Postgres refuses for a referenced table
+  even when the child is empty), and blank CSV fields became SQL `NULL` in `NOT NULL`
+  columns. Insert order and truncation now come from the target's `pg_constraint`
+  graph, and nullability from `information_schema`, so a new foreign key needs no one
+  to remember this.
+- **A fresh install could finish with no way to log in.** The bootstrap password was
+  printed to the pod log exactly once, and `secrets.adminPassword` was only read when
+  the admin user was created — so it did nothing in the one case it was needed. It is
+  now generated into the release Secret like the database password and the JWT key,
+  kept across upgrades, and applied on **every** start, which makes setting it the way
+  to reset it. Read it with `scripts/install.sh password`.
+- **The config seed defaulted to a path from the developer's machine**
+  (`/root/ess-config-values`), so every fresh install logged a `permission denied`
+  warning about a directory that was never theirs. The default is now empty.
+- **A README command could not be pasted**: it contained a literal `…` where the rest
+  of the command belonged, and pasting it produced
+  `non-absolute URLs should be in form of repo_name/path_to_chart, got: %E2%80%A6`.
+
+### Notes
+
+- **0.1.70 was tagged but never published.** The release workflow stopped at its
+  "CHANGELOG must have a section for this version" guard — correctly, but after the
+  tag was already public, so nothing reached GHCR and `helm install` kept resolving
+  0.1.69 while everything local reported success. The same check now runs in
+  `make check` (`scripts/check-changelog.sh`), before a tag exists. The version number
+  is skipped rather than reused: a gap is a more honest record than a moved tag.
+
 ## [0.1.69] — 2026-09-05
 
 ### Fixed

Makefile

@@ -56,6 +56,8 @@ check:
 	$(GO) test ./...
 	cd web && ./node_modules/.bin/tsc -b --noEmit
 	./scripts/check-sensitive.sh
+	./scripts/check-changelog.sh
+	./scripts/check-commands.sh
 	# gofmt is a CI gate, and `make check` did not run it until 2026-08-17 — so
 	# "check green" did not imply "CI green", and E51 shipped unformatted code that
 	# only the pipeline would have caught. A local check that omits a remote gate

README.md

@@ -141,16 +141,51 @@ helm version
 **One more thing if you want HTTPS.** The install command below passes
 `ingress.certIssuer=letsencrypt-prod`, which assumes [cert-manager](https://cert-manager.io/docs/installation/)
 and a `ClusterIssuer` of that name already exist. Install cert-manager first, or
-drop the `--set ingress.certIssuer=…` flag and terminate TLS however you prefer.
+drop the `--set ingress.certIssuer=<issuer>` flag and terminate TLS however you prefer.
 
 Both installer scripts above are piped straight from the internet into a shell.
 That is what the upstream projects document, but read them first if that is not
 acceptable in your environment.
 </details>
 
-### Install (recommended) — OCI chart
+### Install (recommended) — the installer script
 
-The chart and image are published to GHCR, so one command is all you need:
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/bxnnyg/matrixctrl/master/scripts/install.sh)
+```
+
+It asks for a hostname and how you want HTTPS terminated, and checks the rest itself:
+whether `kubectl`/`helm` are there, whether a kubeconfig exists where nothing looks for
+it (k3s writes a root-only one to `/etc/rancher/k3s/k3s.yaml`), whether the cluster
+answers, whether an ingress controller is installed, whether cert-manager has a
+`ClusterIssuer` — and whether a previous install left a database behind, which is the
+one thing that quietly turns a reinstall into an upgrade.
+
+When it finishes it prints the URL, the user, the **admin password**, and the DNS
+record you need. That is the part a bare `helm install` leaves you to find.
+
+Non-interactive, for a script or a second server:
+
+```bash
+./scripts/install.sh install --host matrixctrl.example.com \
+  --tls letsencrypt --issuer letsencrypt-prod --yes
+```
+
+Other subcommands: `password` (prints it again, any time), `status`, `uninstall`.
+
+#### HTTPS — pick one
+
+| `--tls` | What happens | When |
+|---|---|---|
+| `letsencrypt` | cert-manager issues a real certificate | cert-manager and a `ClusterIssuer` exist, and port 80 is reachable. **Not behind Cloudflare's proxy** — HTTP-01 cannot complete through it |
+| `cloudflare-full` | Traefik serves its own default certificate; Cloudflare re-encrypts | Cloudflare proxied, SSL mode **Full**. Nothing to install. Not *Full (strict)* |
+| `cloudflare-flexible` | The origin speaks plain HTTP | Cloudflare proxied, SSL mode **Flexible** |
+| `none` | Plain HTTP | LAN, or a tunnel that terminates TLS itself |
+
+<details>
+<summary><b>Alternative — plain Helm, no script</b></summary>
+
+The chart and image are published to GHCR:
 
 ```bash
 helm install matrixctrl oci://ghcr.io/bxnnyg/charts/matrixctrl \
@@ -159,6 +194,11 @@ helm install matrixctrl oci://ghcr.io/bxnnyg/charts/matrixctrl \
   --set ingress.certIssuer=letsencrypt-prod
 ```
 
+On k3s, `export KUBECONFIG=/etc/rancher/k3s/k3s.yaml` first — without it Helm reports
+`Kubernetes cluster unreachable: dial tcp [::1]:8080` and means "I did not find your
+cluster".
+</details>
+
 No version is pinned here on purpose: Helm resolves the newest published chart, so
 this command cannot go stale. Each released chart pins its own matching image, so
 "newest chart" still means one exact, reproducible pair — not a moving `latest`.
@@ -212,7 +252,7 @@ helm install matrixctrl oci://ghcr.io/bxnnyg/charts/matrixctrl \
    To choose it yourself — at install **or any time after** — set it and upgrade:
 
    ```bash
-   helm upgrade matrixctrl … --set secrets.adminPassword='your-password'
+   ./scripts/install.sh install --admin-password 'your-password'
    ```
 
    The value is applied on every start, so this is also how you reset a password you
@@ -286,13 +326,13 @@ helm upgrade matrixctrl oci://ghcr.io/bxnnyg/charts/matrixctrl -n matrixctrl --r
   --set secrets.adminPassword='your-password'
 ```
 
-> **Upgrading to v0.1.70 sets a new bootstrap password.** The chart generates one into
+> **Upgrading to v0.1.71 sets a new bootstrap password.** The chart generates one into
 > its Secret because there was none there before, and the app applies it on start — so
 > read it back with the command above rather than reusing the old one. This affects only
 > the local `admin` bootstrap login; if you have already switched to **Connect Matrix
 > Login**, that is not how you sign in and nothing changes for you.
 
-> Before v0.1.70 the password was written to the pod log exactly once and
+> Before v0.1.71 the password was written to the pod log exactly once and
 > `secrets.adminPassword` was read only when the account was created — so a restarted pod
 > meant no way in, and reinstalling did not help because `helm uninstall` keeps the
 > database volume. If you are on an older version, upgrade; that alone fixes it.
@@ -321,19 +361,32 @@ scale it back up.
 ### Uninstall
 
 ```bash
-helm uninstall matrixctrl -n matrixctrl
+./scripts/install.sh uninstall
 ```
 
-This deliberately **leaves three things behind**, so that reinstalling does not
-lose your data or lock you out:
+It removes the release, then shows you what Helm kept and offers to delete that
+too — typing `delete` is required, and `--yes` does not cover it.
+
+By hand it is `helm uninstall matrixctrl -n matrixctrl`, which deliberately
+**leaves three things behind**, so that reinstalling does not lose your data or
+lock you out:
 
 | Kept | Why |
 |---|---|
 | `pvc/matrixctrl-config` | the git config repo — every version and rollback point |
 | `pvc/matrixctrl-postgres` | audit log, hooks, upgrade history |
 | `secret/matrixctrl-secret` | DB password and JWT key — regenerating them invalidates every session |
 
-They carry `helm.sh/resource-policy: keep`. To remove everything for real:
+They carry `helm.sh/resource-policy: keep`.
+
+> **This is why "just reinstall it" does not reset anything.** With those volumes
+> in place a fresh `helm install` comes up on the existing database: the schema is
+> already migrated, the admin account already exists, and the install has no new
+> password to give you — it looks like a first install and behaves like an upgrade.
+> If that is what you are trying to escape, delete the volumes below, or use
+> `./scripts/install.sh install`, which notices them and asks.
+
+To remove everything for real:
 
 ```bash
 kubectl delete pvc matrixctrl-config matrixctrl-postgres -n matrixctrl

deploy/helm/matrixctrl/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: matrixctrl
 description: Admin layer for self-hosted Matrix / Element Server Suite (ESS)
 type: application
-version: 0.1.70
-appVersion: "0.1.70"
+version: 0.1.71
+appVersion: "0.1.71"
 keywords:
   - matrix
   - element

docs/DESIGN.md

@@ -2780,3 +2780,83 @@ The general shape, for the next time: **a secret that exists in exactly one plac
 exactly one moment, is not stored — it is announced.** Anything an operator will need
 later has to live somewhere they can query on their own schedule, not somewhere they had
 to be watching.
+
+### §4.75 — Der Fix war fertig, getestet und kam nie an (2026-09-05, operator + agent, etappe 76)
+
+Letzte Runde habe ich §4.74 gemeldet als *ausgeliefert*: `make check` grün, beide
+Integrationstests grün, Image gebaut, in k3s importiert, `helm upgrade` auf Revision 73,
+Pod 2/2, Logzeile aus dem laufenden Container zitiert. Jede einzelne dieser Aussagen war
+wahr.
+
+Der Operator hat auf einer frischen VM installiert und bekam `0.1.69`.
+
+**Der Release-Job war an Schritt 6 gescheitert:** *"CHANGELOG must have a section for
+this version"*. Ich hatte getaggt, ohne den Abschnitt zu schreiben. Der Guard hat exakt
+das getan, wofür er gebaut wurde — nur steht er hinter dem Tag. Ein Tag ist gepusht und
+öffentlich, bevor irgendetwas ihn prüft; was danach fehlschlägt, ist ein Bericht, kein
+Schutz. GHCR blieb auf 0.1.69, `helm install` löste brav „die neueste veröffentlichte
+Version" auf, und der Operator lief in genau den Bug, den 0.1.70 behebt.
+
+Nachgesehen habe ich es nicht. `gh` fehlte auf der Maschine, und dabei habe ich es
+belassen — statt des einen `curl` auf `api.github.com/repos/…/actions/runs`, der zwei
+Sekunden dauert und die Frage beantwortet hätte. „Verifiziert" hieß hier: alles geprüft,
+was ich lokal anfassen konnte, und die eine Sache nicht, die zwischen meiner Maschine und
+seiner steht.
+
+Die Verwechslung dahinter ist benennbar: **in den Cluster deployt ist nicht
+veröffentlicht.** Der lokale k3s ist die Maschine, auf der ich arbeite — dass dort etwas
+läuft, sagt über die Registry nichts. Alle Belege, die ich gesammelt hatte, kamen von der
+falschen Seite der Veröffentlichungsgrenze.
+
+Zwei Konsequenzen, beide vor dem Tag statt danach:
+
+- `scripts/check-changelog.sh` in `make check` — derselbe Guard wie in CI, an der Stelle,
+  wo er noch etwas verhindern kann statt es zu protokollieren.
+- Eine Release-Meldung gilt erst, wenn die Registry sie bestätigt. Der Tag-Push ist die
+  Absicht, nicht das Ergebnis.
+
+0.1.70 wird nicht nachgezogen. Der Tag ist öffentlich, veröffentlicht wurde unter der
+Nummer nichts, und eine Lücke in der Versionsfolge ist ein ehrlicheres Protokoll als ein
+verschobener Tag — die Nummern 0.1.36, 0.1.42 und 0.1.63 fehlen aus demselben Grund.
+
+### §4.76 — Vier Fehlschläge auf dem Weg zu einer Installation, keiner davon in der Software (2026-09-05, operator, etappe 76)
+
+Das Terminal des Operators, in seiner Reihenfolge:
+
+| | Was er sah | Was es hieß |
+|---|---|---|
+| 1 | `Kubernetes cluster unreachable: Get "http://localhost:8080/version"` | `KUBECONFIG` nicht gesetzt. k3s legt sie root-only unter `/etc/rancher/k3s/k3s.yaml` ab |
+| 2 | `These resources were kept due to the resource policy` | `helm uninstall` behält die Volumes. Die Neuinstallation lief auf der alten Datenbank |
+| 3 | Passwort-Secret leer | 0.1.70 war nicht veröffentlicht (§4.75) |
+| 4 | `non-absolute URLs …, got: %E2%80%A6` | Er hat ein README-Kommando mit einem echten `…` darin eingefügt |
+
+Vier Fehlschläge, keiner in MatrixCtrl. Alle vier im Weg dorthin — und jeder einzelne war
+dokumentiert. Die Kubeconfig-Zeile steht im README. Was `helm uninstall` behält, steht im
+README, mit Tabelle und Begründung. Trotzdem hat er zwei Stunden verloren, weil
+Dokumentation zum Zeitpunkt des Fehlers nur hilft, wenn man weiß, wonach man sucht: eine
+Fehlermeldung über Port 8080 schickt niemanden in einen Abschnitt über Kubeconfig-Pfade.
+
+Was fehlte, war nichts Erklärendes, sondern etwas Ausführbares. `scripts/install.sh`
+prüft der Reihe nach genau das, was hier schiefging, und sagt bei jedem Punkt einen Satz
+statt eines Exit-Codes. Die interessanteste Stelle ist Nr. 2: die behaltenen Volumes sind
+**richtig** so — eine Datenbank an einen Vertipper zu verlieren wäre schlimmer —, aber
+ihre Folge wurde nie ausgesprochen. Sie machen die nächste „frische Installation" zu
+einem Upgrade auf altem Bestand: Schema migriert, Admin-Account vorhanden, kein neues
+Passwort zu zeigen. Genau der Zustand, aus dem der Operator herauswollte, war der, den
+Neuinstallieren herstellt. Das Skript fragt jetzt, statt zu raten, und verlangt für das
+Löschen ein getipptes `delete` — `--yes` deckt es bewusst nicht ab: ein Flag, das „hör
+auf zu fragen" bedeutet, darf keine Datenbank löschen.
+
+Nr. 4 hat einen eigenen Guard bekommen (`scripts/check-commands.sh`): in einem
+Shell-Block darf kein `…` stehen. Prosa darf abkürzen; ein Block, den jemand ausführen
+soll, ist eine Anweisung, und eine Anweisung mit einer Lücke ist eine Falle für genau den
+Leser, der nicht weiß, was in die Lücke gehört.
+
+Die TLS-Frage stellt das Skript aus, weil der Operator sie gestellt hat: cert-manager
+(HTTP-01 scheitert hinter Cloudflares Proxy), Cloudflare *Full* (Traefiks
+Default-Zertifikat reicht, nichts zu installieren), Cloudflare *Flexible* (Origin spricht
+HTTP), oder gar kein TLS. Vier Kombinationen aus `entrypoint`/`tls`/`certIssuer`, die man
+einzeln raten kann und dann eine Seite hat, die halb funktioniert.
+
+Der Lauf endet nicht bei `STATUS: deployed`, sondern bei URL, Benutzer, Passwort und dem
+DNS-Record. Eine Installation ist fertig, wenn jemand eingeloggt ist.

docs/ROADMAP.md

@@ -60,8 +60,9 @@ Etappes 1–10 are **reconstructed from `git log`** (39 commits, 2026-05-27 →
 | 32 | Release Notes auf der Upgrade-Seite + Version aus der Liste übernommen — die andere Hälfte der Pin-Warnung | ✅ 2026-08-05 · `v0.1.33` · [plan](plans/etappe-32-release-notes.md) |
 | 33 | OIDC-Init wiederholen statt einmalig aufgeben — ein Neustart vor MAS sperrte den Operator 11 h aus dem eigenen Panel aus | ✅ 2026-08-06 · `v0.1.34` · [plan](plans/etappe-33-oidc-retry.md) |
 | 73 | Der Restore, der nichts wiederhergestellt und Erfolg gemeldet hätte — dazu Skeletons und ein ehrlicher Byte-Zähler | ✅ 2026-09-05 · `v0.1.69` · [plan](plans/etappe-73-silent-restore-and-loading.md) |
-| 74 | Der Restore, der an den eigenen Fremdschlüsseln scheiterte — gefunden vom ersten echten Durchlauf | ✅ 2026-09-05 · `v0.1.70` · [plan](plans/etappe-74-restore-order.md) |
-| 75 | Ein frisches Setup, in das man sich auch anmelden kann — Passwort im Secret statt in einer Logzeile | ✅ 2026-09-05 · `v0.1.70` · [plan](plans/etappe-75-first-login.md) |
+| 74 | Der Restore, der an den eigenen Fremdschlüsseln scheiterte — gefunden vom ersten echten Durchlauf | ✅ 2026-09-05 · `v0.1.71` · [plan](plans/etappe-74-restore-order.md) |
+| 75 | Ein frisches Setup, in das man sich auch anmelden kann — Passwort im Secret statt in einer Logzeile | ✅ 2026-09-05 · `v0.1.71` · [plan](plans/etappe-75-first-login.md) |
+| 76 | Ein Installer, der die vier Fallen auf dem Weg kennt — und ein Release, das ankommt statt nur zu existieren | ✅ 2026-09-05 · `v0.1.71` · [plan](plans/etappe-76-installer.md) |
 | 72 | Ein Backup statt drei Entschuldigungen | ✅ 2026-09-05 · `v0.1.68` · [plan](plans/etappe-72-one-backup.md) |
 | 71 | Wo die Konfiguration wirklich liegt — die beruhigendste Eigenschaft, die nie jemand ausgesprochen hat | ✅ 2026-09-05 · `v0.1.67` · [plan](plans/etappe-71-where-the-config-lives.md) |
 | 70 | Die Volumes — und ein Navigationspunkt, der ins Leere zeigte | ✅ 2026-09-05 · `v0.1.66` · [plan](plans/etappe-70-homeserver-export.md) |