# 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.