gitea-heatmap-sidecar/docs/local.md

Local setup

1. Create a read-only Postgres user

Run db/setup.sql against the Gitea database as a superuser. Edit the password first.

psql -U postgres -d gitea -f db/setup.sql

Only SELECT on "user" and "action" is granted. If Gitea ever renames either table in a migration, the service will break loudly — that's the goal.

2. Build and run the sidecar

Edit docker-compose.example.yml, then:

docker compose -f docker-compose.example.yml up -d --build

Make sure the networks block matches your existing Gitea Docker network so the sidecar can reach gitea-db by hostname.

Required env vars:

Var	Description
DATABASE_URL	postgres://heatmap_ro:...@host:5432/gitea?sslmode=...
ALLOWED_USERS	Comma-separated lowercase usernames (e.g. didericis)
ALLOWED_ORIGIN	CORS origin — must match Gitea's URL
OP_TYPES	Optional. Comma-separated op_type ints. See README.
LISTEN	Optional. Default :8080.

3. Reverse proxy

Expose the service at a hostname Gitea's frontend can reach over HTTPS — e.g. heatmap.dideric.is → heatmap:8080. Use the same TLS setup as Gitea itself (Caddy/Traefik/nginx).

4. Install the profile template override

Copy templates/user/profile.tmpl from the Gitea source matching your running version into $GITEA_CUSTOM/templates/user/profile.tmpl, then merge in the snippet from templates/profile-snippet.tmpl near the existing heatmap block.

Replace HEATMAP_BASE_URL in the snippet with your sidecar's public URL (e.g. https://heatmap.dideric.is) and didericis with the username you're exposing.

Restart Gitea, hit the profile page in incognito, and you should see the heatmap populate.