Rename docs/local-setup.md to docs/local.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-05 15:48:40 -04:00
parent 28546204fe
commit da219f331b
3 changed files with 2 additions and 2 deletions
@@ -0,0 +1,54 @@
+# 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.