umami/AGENTS.md

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