Joakim Mörling
737bc3dc64
Enable pageview tracking when VITE_UMAMI_WEBSITE_ID is set at frontend build time (Forgejo secret + deploy workflow), with SPA route updates and no script in local dev. Document setup in docs/umami-analytics.md, extend integritetspolicy, and add admin Webbstatistik link in prod builds. Co-authored-by: Cursor <cursoragent@cursor.com>
81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# Umami analytics (BilHej app)
|
|
|
|
Privacy-friendly page analytics via self-hosted [Umami](https://umami.is/docs) on **`https://analytics.bilhej.se`**. Server install is live on the VPS; this doc is for **BilHej code and deploy config** only.
|
|
|
|
## Values (production)
|
|
|
|
| Item | Value |
|
|
|------|--------|
|
|
| Collector | `https://analytics.bilhej.se` |
|
|
| Tracker script | `https://analytics.bilhej.se/script.js` |
|
|
| Dashboard | `https://analytics.bilhej.se` (admin login) |
|
|
| Website in Umami | Name **BilHej**, domain **`bilhej.se`** |
|
|
| Website ID | `ce59614c-9f2a-4f99-8ba3-c5217f88c3f7` |
|
|
|
|
The Website ID is public in the browser (tracking snippet). Set it via **`VITE_UMAMI_WEBSITE_ID`** in production frontend build env — do not hardcode in source.
|
|
|
|
**Note:** Umami 3.1 on this server uses the default **`/script.js`** path. `TRACKER_SCRIPT_NAME` / custom `bilhej-stats.js` is not applied in this version.
|
|
|
|
### Example snippet (for reference)
|
|
|
|
```html
|
|
<script
|
|
defer
|
|
src="https://analytics.bilhej.se/script.js"
|
|
data-website-id="ce59614c-9f2a-4f99-8ba3-c5217f88c3f7"
|
|
></script>
|
|
```
|
|
|
|
## Frontend env
|
|
|
|
Production builds read this from the **Forgejo Actions secret** `VITE_UMAMI_WEBSITE_ID`. The deploy workflow writes it into `.env` on the server, then `docker compose -f docker-compose.prod.yml build` bakes it into the frontend image.
|
|
|
|
**Forgejo → Repository → Settings → Actions → Secrets:**
|
|
|
|
| Secret | Value |
|
|
|--------|--------|
|
|
| `VITE_UMAMI_WEBSITE_ID` | `ce59614c-9f2a-4f99-8ba3-c5217f88c3f7` |
|
|
|
|
Not a high-risk secret (the same ID appears in the browser), but keeping it in Forgejo matches other deploy config.
|
|
|
|
Manual deploy on the server (without Forgejo) works the same way: put the line in the project `.env` before `docker compose ... up --build`.
|
|
|
|
Optional override (default matches production):
|
|
|
|
```bash
|
|
# VITE_UMAMI_SCRIPT_URL=https://analytics.bilhej.se/script.js
|
|
```
|
|
|
|
Leave `VITE_UMAMI_WEBSITE_ID` unset in local dev unless you intentionally send traffic to production Umami.
|
|
|
|
## Implementation checklist
|
|
|
|
- [x] Load `script.js` with `data-website-id` from `VITE_UMAMI_WEBSITE_ID` (only when set).
|
|
- [x] Send **SPA pageviews** on Vue Router `afterEach` (`data-auto-track="false"`).
|
|
- [x] Update **integritetspolicy** — analytics, country-level stats, no IP stored in BilHej DB.
|
|
- [x] Admin link **Webbstatistik** → Umami dashboard (prod builds only).
|
|
|
|
Umami derives **country** from the visitor IP at ingest and does not show IP lists in the UI. BilHej must not store visitor IPs for analytics.
|
|
|
|
## Verify after deploy
|
|
|
|
1. Browse `https://bilhej.se` (several routes).
|
|
2. Umami → **BilHej** → **Realtime** / **Countries**.
|
|
|
|
## Server layout (reference)
|
|
|
|
| Item | Actual on VPS |
|
|
|------|----------------|
|
|
| Compose project | `~/umami` (`/home/jocke/umami`) |
|
|
| Public access | nginx → `http://umami:3000` on Docker network `web` (host port 3000 used by open-webui) |
|
|
| Database | `umami-db` on internal network `umami-internal` only |
|
|
|
|
```bash
|
|
cd ~/umami
|
|
docker compose ps
|
|
docker compose logs -f umami
|
|
docker compose pull && docker compose up -d # updates — read release notes first
|
|
docker exec umami-db pg_dump -U umami umami > ~/umami-backup-$(date +%F).sql
|
|
```
|
|
|
|
Country stats require nginx to pass **`X-Forwarded-For`** (already configured for this vhost).
|