Voeg self-hosted Umami analytics + UptimeRobot uptime dashboard toe

Co-authored-by: Junie <junie@jetbrains.com>
2026-07-25 19:59:40 +02:00
parent da2a6e03ea
commit 08b489e305
15 changed files with 405 additions and 29 deletions
@@ -0,0 +1,110 @@
+# 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:
+   ```bash
+   cd ~/umami
+   podman-compose up -d
+   ```
+4. Controleer dat Umami draait en bereikbaar is op het interne netwerk:
+   ```bash
+   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:
+   ```bash
+   sudo loginctl enable-linger $(whoami)
+   ```
+2. Maak `~/.config/systemd/user/umami.service` aan:
+   ```ini
+   [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:
+   ```bash
+   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:
+   ```bash
+   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.