aidlc-docs/features/react-frontend/audit.md

@@ -600,3 +600,15 @@
 **Context**: Post-workflow follow-up (feature already marked Complete); continues the `feature/analytics_uptime_dashboard` branch, fixing a port conflict discovered before the Umami deployment has been executed on the Pi. Documentation/example-config-only change (no code/build impact).
 
 ---
+
+## Post-Completion Follow-up: Clarified `podman-compose down`/`up -d` Needed After Config Changes to an Already-Created Container
+
+**Timestamp**: 2026-07-25T22:57:00Z
+
+**User Input**: "maakt het uit dat ik al podman-compose heb uitgevoerd? moet ik nu eerst de container verwijderen?" (asking whether it matters that `podman-compose up -d` had already been run with the old port-3000 config, before the port-3001 fix).
+
+**AI Response**: "Explained that a port mapping is set at container-creation time and is not live-reloaded by `podman-compose up -d` on an already-existing container, so after updating the local `podman-compose.yml` to the new port, a `podman-compose down` followed by `podman-compose up -d` is required to recreate the container with the corrected mapping (database data is preserved via the persistent volume). Added a callout to `umami-setup.md` documenting this `down`/`up` requirement for future config changes (e.g. another port change), so this is not only explained in chat but also captured for later reference."
+
+**Context**: Post-workflow follow-up (feature already marked Complete); continues the `feature/analytics_uptime_dashboard` branch, clarifying the deployment steps before the Umami container has successfully started on the Pi. Documentation-only change (no code/build impact).
+
+---

aidlc-docs/features/react-frontend/operations/monitoring/umami-setup.md

@@ -82,6 +82,24 @@ onder een eigen `umami`-user te draaien in plaats van je eigen hoofdaccount:
    ```
    Dit zou een JSON-antwoord met `"ok"` moeten teruggeven.
 
+> **Let op — na een wijziging aan `podman-compose.yml`/`.env` (bv. een andere poort):**
+> `podman-compose up -d` update alléén containers waarvan de configuratie is gewijzigd,
+> maar een poortmapping (`ports:`) wordt door Podman **niet** live herladen op een
+> bestaande, al aangemaakte container. Heb je `podman-compose up -d` al eerder gedraaid
+> met een oude versie van `podman-compose.yml` (bv. met poort `3000` in plaats van
+> `3001`), werk dan eerst je lokale `~/umami/podman-compose.yml` bij met de nieuwste
+> versie uit dit repository, en draai daarna:
+> ```bash
+> cd ~/umami
+> podman-compose down
+> podman-compose up -d
+> ```
+> `podman-compose down` verwijdert de containers (niet de database-data, die staat in
+> een persistent volume) en `up -d` maakt ze opnieuw aan met de bijgewerkte poort/config.
+> Dit is enkel nodig als de container al bestond met de oude configuratie; bij een
+> eerste, nieuwe `up -d` (of als de vorige poging überhaupt nooit is gestart doordat
+> Podman de poort niet kon claimen) is dit niet nodig.
+
 ## 2. Automatisch starten na reboot (systemd user service)
 Podman-compose start niet vanzelf op na een herstart van de Pi, tenzij je dit expliciet
 instelt. Omdat rootless Podman hier al gebruikt wordt, is een systemd **user**-service —