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.

Umami draait onder een eigen dedicated Linux-user (umami) in plaats van onder het bestaande hoofdaccount, zodat elke self-hosted service (nu en in de toekomst) netjes geïsoleerd blijft — zie "Waarom een dedicated user" hieronder. Dit patroon kan hergebruikt worden voor volgende self-hosted diensten op dezelfde Pi('s).

Vereisten

• Podman is al aanwezig op de Pi (bevestigd door de gebruiker) — systeembreed geïnstalleerd, dus beschikbaar voor elke user, ook een nieuw aangemaakte.
• podman-compose geïnstalleerd voor de umami-user: pip3 install --user podman-compose (of via de package manager van je distro, indien beschikbaar) — zie stap 0 hieronder.
• 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).

Waarom een dedicated user

Podman zelf hoeft niet per user geïnstalleerd te worden (het is een systeembreed pakket), maar rootless Podman-containers erven wél de rechten van de user die ze start. Door Umami onder een eigen umami-user te draaien in plaats van je eigen hoofdaccount:

• kan een kwetsbaarheid in de Umami-container (zelfs bij een container-escape binnen de rootless-namespace) geen bestanden van je persoonlijke account lezen/schrijven;
• houd je containerstorage, systemd user-services en logs van verschillende self-hosted diensten netjes gescheiden per user, ook als je Pi qua rekenkracht beperkt is;
• kun je dit patroon straks 1-op-1 hergebruiken voor een volgende self-hosted dienst (bv. een eigen uptime-user, git-user, etc.), zonder dat diensten elkaars bestanden kunnen benaderen.

0. Dedicated umami-user aanmaken (op de webserver-Pi)

1. Maak de user aan (zonder wachtwoord-login is prima, we loggen in via sudo -iu umami of su - umami):

   sudo useradd --create-home --shell /bin/bash umami
   sudo passwd -l umami   # login met wachtwoord blokkeren, sudo -iu blijft werken
   

2. Controleer dat er een subuid/subgid-range is toegewezen (nodig voor rootless Podman). Op de meeste moderne distributies (incl. Raspberry Pi OS) gebeurt dit automatisch bij useradd:

   grep umami /etc/subuid /etc/subgid
   

   Zie je geen output, voeg dan handmatig een range toe (pas de startwaarde aan als die al in gebruik is door een andere user):

   sudo usermod --add-subuids 200000-265535 --add-subgids 200000-265535 umami
   

3. Zorg dat de umami-sessie blijft "linger-en", zodat rootless Podman-services ook actief blijven zonder dat de user is ingelogd (nodig voor stap 2 hieronder):

   sudo loginctl enable-linger umami
   

4. Log in als de nieuwe user om de rest van de setup uit te voeren:

   sudo -iu umami
   

1. Umami + database opzetten (als de umami-user, op de webserver-Pi)

0. Installeer podman-compose voor deze user, indien nog niet systeembreed aanwezig:

   pip3 install --user podman-compose
   

1. Maak een map aan, bv. ~/umami/ (dit is nu /home/umami/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. Let op: de externe poort is 3001, niet het gebruikelijke 3000 — die poort is op deze Pi al in gebruik door Gitea (bind: address already in use bij het opstarten van de container als je toch 3000 gebruikt):

   curl http://192.168.1.103:3001/api/heartbeat
   

   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:

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 — gekoppeld aan de umami-user — de eenvoudigste aanpak. De loginctl enable-linger umami uit stap 0.3 is hiervoor al gezet, dus deze service blijft ook draaien zonder dat de umami-user zelf is ingelogd.

1. Log in (of blijf ingelogd) als de umami-user: sudo -iu umami.
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 (nog steeds als de umami-user):

   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

• Dedicated umami-user aanmaken op Pi Main (incl. subuid/subgid-check en loginctl enable-linger).
• podman-compose up -d daadwerkelijk draaien als de umami-user op Pi Main.
• Systemd user-service instellen (onder de umami-user) 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.

Vervolgstappen voor toekomstige self-hosted diensten

Dit dedicated-user-patroon (stap 0 hierboven) is bewust generiek gehouden zodat het hergebruikt kan worden: een volgende self-hosted dienst op dezelfde of een andere Pi kan op dezelfde manier zijn eigen user krijgen (bv. useradd --create-home, subuid/subgid controleren, loginctl enable-linger <user>, eigen ~/.config/systemd/user/<dienst>.service), zodat diensten onderling geïsoleerd blijven zonder dat dit ten koste gaat van de al beperkte rekenkracht van een Raspberry Pi (rootless Podman zelf blijft immers systeembreed gedeeld, alleen de user-context verandert per dienst).