# Local setup

### 1. Create a read-only Postgres user

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

```bash
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:

```bash
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.