From ba66aba2864096a175e56be3b91037aff0be97f1 Mon Sep 17 00:00:00 2001
From: didericis <you@dideric.is>
Date: Tue, 5 May 2026 15:31:28 -0400
Subject: [PATCH] Add TrueNAS SCALE setup guide to README

Step-by-step instructions for Electric Eel (24.10+): finding the DB
container and network, creating the read-only user, deploying with
docker compose, reverse proxying, and locating the Gitea custom dir.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/README.md b/README.md
index e033587..9e05add 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,97 @@ exposing.
 Restart Gitea, hit the profile page in incognito, and you should see the
 heatmap populate.
 
+## 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 main setup](#4-install-the-profile-template-override)
+to install the template override into that directory and restart Gitea.
+
 ## Op type reference
 
 Gitea's `action.op_type` is an integer enum. Defaults are commits-only