Move setup guides into docs/

Splits local-setup and TrueNAS SCALE instructions into
docs/local-setup.md and docs/truenas.md; README now links to both.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/local-setup.md

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

docs/truenas.md

@@ -0,0 +1,90 @@
+# TrueNAS SCALE setup
+
+Tested on TrueNAS SCALE 24.10 (Electric Eel) with Gitea installed via the
+official app catalog. All commands below run over SSH on the TrueNAS host.
+
+### 1. Find Gitea's DB container and Docker network
+
+```bash
+# List Gitea-related containers
+docker ps --format '{{.Names}}' | grep -i gitea
+
+# Find the network the Gitea app container is on
+docker inspect <gitea-app-container> \
+  --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{end}}'
+```
+
+Note both the DB container name (typically ends in `-postgres` or `-db`) and
+the network name — you'll need them in the steps below.
+
+### 2. Get the Gitea DB password
+
+In the TrueNAS UI: **Apps → Installed Apps → Gitea → Edit → Database
+Configuration**. The Postgres password is visible there. You'll use it in
+steps 3 and 4.
+
+### 3. Create the read-only DB user
+
+Edit `db/setup.sql` to set a password for `heatmap_ro`, then run it against
+the DB container:
+
+```bash
+docker exec -i <gitea-db-container> psql -U gitea -d gitea < db/setup.sql
+```
+
+### 4. Clone and configure
+
+Put the repo somewhere on persistent storage:
+
+```bash
+git clone https://github.com/didericis/gitea-heatmap-sidecar \
+  /mnt/<pool>/gitea-heatmap-sidecar
+cd /mnt/<pool>/gitea-heatmap-sidecar
+cp docker-compose.example.yml docker-compose.yml
+```
+
+Edit `docker-compose.yml`:
+
+- Set `DATABASE_URL` — use the DB container name as the hostname, e.g.
+  `postgres://heatmap_ro:PASSWORD@gitea-db-container-name:5432/gitea?sslmode=disable`
+- Set `ALLOWED_USERS` and `ALLOWED_ORIGIN`
+- Under `networks.gitea`, set `name` to the network name from step 1 and
+  uncomment `external: true`
+
+### 5. Build and start
+
+```bash
+docker compose -f /mnt/<pool>/gitea-heatmap-sidecar/docker-compose.yml up -d --build
+```
+
+Confirm it's healthy:
+
+```bash
+docker exec gitea-heatmap wget -qO- http://localhost:8080/healthz
+```
+
+### 6. Reverse proxy
+
+Expose port 8080 at a public HTTPS hostname. With **Nginx Proxy Manager**
+(a common TrueNAS app on the same Docker network):
+
+- Scheme: `http`, Forward hostname: `gitea-heatmap` (the container name),
+  Port: `8080`
+- Enable SSL via Let's Encrypt
+
+For Traefik or Caddy configured as TrueNAS apps, wire it up the same way —
+the sidecar is reachable by container name on the shared network.
+
+### 7. Find the Gitea custom directory
+
+In the TrueNAS UI: **Apps → Installed Apps → Gitea → Edit → Storage**.
+Find the host path mapped to the Gitea data volume. The custom directory
+Gitea reads templates from is the `custom/` subdirectory of that path —
+check the `GITEA_CUSTOM` env var in the container if unsure:
+
+```bash
+docker exec <gitea-app-container> printenv GITEA_CUSTOM
+```
+
+Then follow [step 4 of the local setup](local-setup.md#4-install-the-profile-template-override)
+to install the template override into that directory and restart Gitea.