48 lines
3.6 KiB
Markdown
48 lines
3.6 KiB
Markdown
# Agent guide – Umami analytics stack
|
||
|
||
This repo is a **self-hosted Umami analytics stack** for deployment via **Portainer** (stack from repository). It does not contain application source code; it defines the Docker Compose stack, CI, and docs.
|
||
|
||
## Purpose
|
||
|
||
- Run [Umami](https://umami.is) (privacy-focused analytics) with PostgreSQL.
|
||
- Reverse proxy: **Traefik** on the existing Docker network **marina-net**.
|
||
- Deploy by adding the stack in Portainer and pointing it at this repo.
|
||
|
||
## Architecture
|
||
|
||
- **marina-net** (external): Shared network where Traefik runs. Only the **umami** service from this stack is attached so Traefik can route to it. No database on this network.
|
||
- **umami-backend** (internal): Only **umami** and **db** (PostgreSQL). Isolated from Traefik and the rest of the host.
|
||
- **umami** is on both networks; **db** is only on umami-backend.
|
||
- **Volumes**: One external volume, **umami-db-data**, for PostgreSQL data. Declared with `external: true`; the user must create it (e.g. `docker volume create umami-db-data`) before first deploy.
|
||
|
||
## Design decisions
|
||
|
||
- **No secrets in repo**: All sensitive values (APP_SECRET, POSTGRES_PASSWORD, etc.) come from Portainer stack environment variables or a local `.env`; see `.env.example` and SETUP.md.
|
||
- **External volume only**: DB data lives in a named external volume with an `umami-` prefix so it is explicit and portable.
|
||
- **Traefik Host rule**: Default host is **analytics.mifi.holdings**; can be changed in `docker-compose.yml` if deploying elsewhere. HTTPS is handled by Traefik (entrypoints `web` and `websecure`); no cert paths in this repo.
|
||
- **Variable substitution**: Compose uses `${POSTGRES_DB}`, `${POSTGRES_USER}`, `${POSTGRES_PASSWORD}`, `${APP_SECRET}` so Portainer (or `.env`) injects values.
|
||
|
||
## Key files
|
||
|
||
| File | Role |
|
||
| ------------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| `docker-compose.yml` | Stack definition: services, networks, volumes, Traefik labels, env substitution. |
|
||
| `.env.example` | List of env var names and placeholders; no real values. |
|
||
| `SETUP.md` | Human-facing setup: volume creation, secret generation, Portainer env vars, Host rule, first login. |
|
||
| `AGENTS.md` | This file; for agents and developers. |
|
||
| `.woodpecker/ci.yaml` | CI: install deps, format check (Prettier). |
|
||
| `.woodpecker/deploy.yaml` | Deploy: trigger Portainer webhook after CI (no image build in this repo). |
|
||
|
||
## Where to change things
|
||
|
||
- **Traefik hostname**: In `docker-compose.yml`, label `traefik.http.routers.umami.rule=Host(\`...\`)`. Default is **analytics.mifi.holdings**.
|
||
- **Secrets**: Only in Portainer stack env or a local `.env`; never commit real values.
|
||
- **DB volume name**: Compose uses `umami-db-data`; if you change it, update the `volumes` section and document the new name (e.g. in SETUP.md).
|
||
|
||
## Deployment context
|
||
|
||
- **Repo**: `git.mifi.dev/mifi-holdings/umami.git`
|
||
- **CI**: Woodpecker; pipelines under `.woodpecker/` (ci, deploy). Deploy depends on **ci** (not build); this repo has no Docker image build (stack-from-repo only).
|
||
- **Prerequisites**: Existing Docker network **marina-net** and Traefik so the Umami service can be reached via the configured host.
|
||
- **First login**: No default credentials; the admin account is created in the Umami UI on first visit.
|