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

Umami Self-Hosted Setup (Analytics)

Stapsgewijze handleiding om Umami (self-hosted website-analytics) op te zetten op de webserver-Pi (Pi Main, 192.168.1.103) met Podman, en bereikbaar te maken via analytics.slpsoftware.nl. Dit vult het "Analytics/uptime dashboard" open item uit operations/production-readiness-checklist.md in voor het analytics-gedeelte.

Vereisten

• Podman is al aanwezig op de Pi (bevestigd door de gebruiker).
• podman-compose geïnstalleerd: pip3 install --user podman-compose (of via de package manager van je distro, indien beschikbaar).
• DNS: een A-record voor analytics.slpsoftware.nl dat naar het publieke IP van de reverse-proxy-Pi wijst (dezelfde Pi die ook test.slpsoftware.nl afhandelt).

1. Umami + database opzetten (op de webserver-Pi)

1. Maak een map aan, bv. ~/umami/, en kopieer daarin:
   • operations/deployment/umami/podman-compose.yml.example → ~/umami/podman-compose.yml
   • operations/deployment/umami/.env.example → ~/umami/.env
2. Vul in ~/umami/.env een echte POSTGRES_PASSWORD en APP_SECRET in (bv. via openssl rand -base64 32 voor beide — gebruik twee verschillende waarden).
3. Start de containers:

   cd ~/umami
   podman-compose up -d
   

4. Controleer dat Umami draait en bereikbaar is op het interne netwerk:

   curl http://192.168.1.103:3000/api/heartbeat
   

   Dit zou een JSON-antwoord met "ok" moeten teruggeven.

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 de eenvoudigste aanpak:

1. Zorg dat de gebruiker-sessie blijft "linger-en" na uitloggen/reboot:

   sudo loginctl enable-linger $(whoami)
   

2. Maak ~/.config/systemd/user/umami.service aan:

   [Unit]
   Description=Umami analytics (podman-compose)
   After=network-online.target
   
   [Service]
   WorkingDirectory=%h/umami
   ExecStart=/usr/bin/podman-compose up
   ExecStop=/usr/bin/podman-compose down
   Restart=on-failure
   
   [Install]
   WantedBy=default.target
   

3. Activeer en start de service:

   systemctl --user daemon-reload
   systemctl --user enable --now umami.service
   

3. Reverse proxy + SSL (op de reverse-proxy-Pi)

1. Kopieer operations/deployment/nginx/analytics-nginx.conf.example naar bv. /etc/nginx/sites-available/slpsoftware-analytics.conf op de reverse-proxy-Pi, en maak een symlink in sites-enabled.
2. Zorg dat het DNS-record voor analytics.slpsoftware.nl al actief is, en draai dan:

   sudo certbot --nginx -d analytics.slpsoftware.nl
   

3. Herlaad nginx: sudo nginx -t && sudo systemctl reload nginx.
4. Test: open https://analytics.slpsoftware.nl in de browser — je zou het Umami-inlogscherm moeten zien (standaard inloggegevens: admin / umami, direct wijzigen na eerste login).

4. Website registreren in Umami en het website-ID ophalen

1. Log in op https://analytics.slpsoftware.nl en wijzig direct het standaardwachtwoord.
2. Ga naar Settings → Websites → Add website en vul in:
   • Name: SLP Software (of naar keuze)
   • Domain: het domein van de daadwerkelijke website (bv. slpsoftware.nl of test.slpsoftware.nl, afhankelijk van welke omgeving je eerst wilt meten)
3. Na het opslaan toont Umami een Website ID (een UUID) — dit heb je nodig voor de volgende stap.

5. Tracking script koppelen aan de website (build-configuratie)

De React-app (src/components/UmamiAnalytics.tsx) injecteert het Umami tracking-script automatisch, mits de volgende twee build-time variabelen zijn ingesteld — beide zijn geen secrets (client-side zichtbaar), dus als Gitea Actions repository variables (niet secrets), net als VITE_SENTRY_DSN:

Variabele	Waarde
VITE_UMAMI_SCRIPT_URL	https://analytics.slpsoftware.nl/script.js
VITE_UMAMI_WEBSITE_ID	het Website ID uit stap 4

Stel deze in via Gitea → Repository Settings → Actions → Variables. Zodra beide bestaan, pakt de eerstvolgende build ze automatisch op; zonder deze variabelen slaat de app het inladen van het script gewoon over (geen crash, geen tracking).

Lokaal (pnpm dev): het tracking-script wordt hier bewust nooit geladen (zie UmamiAnalytics.tsx), zodat lokaal testen de bezoekersstatistieken niet vervuilt. Wil je dit toch lokaal testen, zet dan tijdelijk beide waarden in .env.local (zie .env.example) én verwijder tijdelijk de import.meta.env.DEV-check.

Openstaande handmatige stappen

• podman-compose up -d daadwerkelijk draaien op Pi Main.
• Systemd user-service instellen voor auto-start na reboot.
• DNS-record + certbot voor analytics.slpsoftware.nl op de reverse-proxy-Pi.
• Standaard Umami-wachtwoord direct wijzigen na eerste login.
• Website aanmaken in Umami en het Website ID overnemen.
• VITE_UMAMI_SCRIPT_URL en VITE_UMAMI_WEBSITE_ID als Gitea repository variables instellen.