gitea-heatmap-sidecar/docs/truenas.md

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

# 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:

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:

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

docker compose -f /mnt/<pool>/gitea-heatmap-sidecar/docker-compose.yml up -d --build

Confirm it's healthy:

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:

docker exec <gitea-app-container> printenv GITEA_CUSTOM

Then follow step 4 of the local setup to install the template override into that directory and restart Gitea.