optimized events

deploy/README.md

@@ -1,9 +1,10 @@
 # Watermaps-Produktion
 
-Dieser Stack hostet die Watermaps-App und die lokalen Fahrrouten für
-Deutschland und die Niederlande. Die sichtbaren Kartenkacheln bleiben externe
-Dienste. Öffentlich gebunden werden ausschließlich TCP 80 und 443; die
-Watermaps-App ist nur im internen Docker-Netz erreichbar.
+Dieser Stack hostet die Watermaps-App, die lokalen Fahrrouten sowie eine
+persistente PostGIS-Datenbank für Häfen, Schleusen, Brücken und Kontaktdaten in
+Deutschland und den Niederlanden. Die sichtbaren Kartenkacheln bleiben externe
+Dienste. Öffentlich gebunden werden ausschließlich TCP 80 und 443; App und
+PostGIS sind nur im internen Docker-Netz erreichbar.
 
 ## Konfiguration
 
@@ -12,11 +13,19 @@ cp deploy/.env.production.example deploy/.env.production
 editor deploy/.env.production
 ```
 
-Mindestens `WATERMAPS_ACME_EMAIL` muss angepasst werden. Außerdem müssen
-`WATERMAPS_REGISTRY` und `WATERMAPS_REGISTRY_OWNER` auf die Gitea Container
-Registry zeigen. Der Hetzner-API-Token gehört **nicht** in diese Datei. Er
-bleibt lokal in der ignorierten Datei `infra/opentofu/terraform.tfvars`
-(alternativ kann der Provider `TF_VAR_hcloud_token` lesen).
+Mindestens `WATERMAPS_ACME_EMAIL` und `WATERMAPS_POSTGRES_PASSWORD` müssen
+angepasst werden. Für das Datenbankpasswort eignet sich ein URL-unabhängiges
+Hex-Secret:
+
+```bash
+openssl rand -hex 32
+```
+
+Außerdem müssen `WATERMAPS_REGISTRY` und `WATERMAPS_REGISTRY_OWNER` auf die
+Gitea Container Registry zeigen. Der Hetzner-API-Token gehört **nicht** in
+diese Datei. Er bleibt lokal in der ignorierten Datei
+`infra/opentofu/terraform.tfvars` (alternativ kann der Provider
+`TF_VAR_hcloud_token` lesen).
 
 Die private SSH-Keydatei wird ebenfalls nicht gespeichert. Sie kann beim
 Deployment mit `--identity` oder über `WATERMAPS_SSH_KEY` angegeben werden.
@@ -53,8 +62,8 @@ werden nur Tests ausgeführt; Registry-Secrets werden dabei nicht verwendet.
 Nach einem erfolgreichen Image-Build liest das Skript standardmäßig den
 OpenTofu-Output `server_ipv4`. Es erlaubt ausschließlich einen sauberen,
 vollständig committeten Git-Stand und überträgt nur den kleinen Ordner
-`deploy/`, nicht den Anwendungsquellcode. Die Image-Tags entsprechen exakt
-`git rev-parse HEAD`.
+`deploy/` sowie das kanonische `database/schema.sql`, nicht den
+Anwendungsquellcode. Die Image-Tags entsprechen exakt `git rev-parse HEAD`.
 
 Ist die Registry privat, werden einmalig beziehungsweise nach Tokenwechsel
 lokale Pull-Zugangsdaten mitgegeben:
@@ -78,20 +87,36 @@ Anmeldung gültig ist:
   --identity ~/.ssh/watermaps_hetzner_ed25519
 ```
 
-Das Serverskript lädt App, Routingdaten-Builder, Nginx und Certbot mit
-`docker compose pull`. Die beiden commitgenauen Gitea-Tags werden anschließend
-in ihre unveränderlichen Registry-Digests aufgelöst. Erst danach werden die
-Container mit `--no-build` gestartet. Der Produktionsserver benötigt deshalb
-weder Git noch Node/npm oder den Quellcode.
+Das Serverskript lädt App, den kombinierten Routing-/Feature-Daten-Builder,
+PostGIS, Nginx und Certbot mit `docker compose pull`. Die beiden commitgenauen
+Gitea-Tags werden anschließend in ihre unveränderlichen Registry-Digests
+aufgelöst. Erst danach werden die Container mit `--no-build` gestartet. Der
+Produktionsserver benötigt deshalb weder Git noch Node/npm oder den Quellcode.
 
 Der erste Datenaufbau lädt die Geofabrik-Extrakte für Deutschland und die
-Niederlande herunter und kann entsprechend der Serverleistung längere Zeit
-dauern. Der produktive Index liegt auf dem Server unter:
+Niederlande, baut den Fahrroutenindex und importiert daraus die
+`marine_features`. Je nach Serverleistung kann dies längere Zeit dauern.
+App und Nginx werden beim ersten Release erst gestartet, wenn sowohl der
+Routingindex als auch ein nicht leerer, zur PBF-Prüfsumme passender Bestand an
+Häfen, Schleusen und Brücken geprüft wurde. Ein HTTP-Healthcheck allein kann
+damit keine leere Ereignisdatenbank freigeben.
+
+Die produktiven Daten liegen auf dem persistenten Servervolume:
 
 ```text
 /srv/watermaps-data/local/germany-netherlands-fairways.json
+/srv/watermaps-data/local/.marine-features.ready
+/srv/watermaps-data/postgres/
+/srv/watermaps-data/tmp/
 ```
 
+PostGIS veröffentlicht keinen Host-Port. Die App verbindet sich im privaten
+Compose-Netz; das Passwort wird separat über `PGPASSWORD` übergeben und muss
+nicht URL-kodiert in `DATABASE_URL` dupliziert werden. Auch die temporären,
+potenziell mehrere Gigabyte großen Filter- und GeoJSON-Dateien des Imports
+liegen unter `tmp/` auf diesem Volume und nicht im Docker-Overlay der
+Rootdisk; nach jedem Importlauf werden sie entfernt.
+
 Der Upload wartet zuerst auf SSH und den Abschluss von Cloud-init. Anschließend
 startet und prüft er `watermaps-volume-setup.service`. Ohne tatsächlich unter
 `/srv/watermaps-data` eingehängtes Volume wird kein Download gestartet, damit
@@ -108,7 +133,10 @@ HTTP-Anfragen erhalten 404.
 Jedes erfolgreiche Release wird mit Commit-SHA und den aufgelösten
 Image-Digests unter `/srv/watermaps-runtime/deployments/` gespeichert. Scheitert
 ein Deployment nach dem Containerwechsel, startet `deploy.sh` automatisch das
-vorherige Release und führt die Health- und Routentests erneut aus.
+vorherige Release und führt die Health-, Routen- und Featuretests erneut aus.
+Ein Rollback wechselt nur die unveränderlichen App-/Builder-Images. Die
+persistente PostGIS-Datenbank bleibt erhalten; das Schema und der Import sind
+aufwärtskompatibel und idempotent.
 
 Das unmittelbar vorherige Release lässt sich auch manuell aktivieren:
 
@@ -153,11 +181,26 @@ HTTPS um.
 `bootstrap-server.sh` installiert zwei systemd-Timer:
 
 - `watermaps-route-update.timer`: täglich neue Deutschland- und
-  Niederlande-Daten; bei Build- oder Routentestfehler bleibt der vorherige
-  Index aktiv.
+  Niederlande-Daten. Der Fahrroutenindex wird atomar aktiviert. Der
+  Feature-Importer aktualisiert beide Länder per Upsert und entfernt
+  verschwundene Datensätze erst, nachdem beide Importe vollständig waren;
+  dabei werden ausschließlich OSM-Zeilen bereinigt. EuRIS- und
+  Website-Anreicherungen bleiben erhalten.
 - `watermaps-certbot-renew.timer`: zweimal täglich Certbot-Prüfung mit
   anschließendem Nginx-Reload.
 
+Ein vollständiger manueller Feature-Neuimport lässt sich über die
+Option `--force-marine` erzwingen:
+
+```bash
+/opt/watermaps/deploy/scripts/update-route-data.sh --force-marine
+```
+
+`WATERMAPS_REBUILD_MARINE_DATA=true` in `.env.production` erzwingt den
+Neuimport stattdessen beim nächsten regulären Deployment. Der systemd-Dienst
+hat bewusst kein Startzeitlimit, da Download, Indexbau und Import auf kleineren
+Servern deutlich länger als 90 Sekunden dauern können.
+
 Status und Logs:
 
 ```bash