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 shell commands run over SSH on the TrueNAS host.

1. Publish the image

The Custom App Wizard requires a pre-built image in a container registry. The Gitea instance you're already running works fine for this.

On your development machine (or directly on TrueNAS):

docker login gitea.yourdomain.com

docker build -t gitea.yourdomain.com/yourusername/gitea-heatmap-sidecar:latest .
docker push gitea.yourdomain.com/yourusername/gitea-heatmap-sidecar:latest

Make the package public in Gitea under Settings → Packages, or configure TrueNAS with registry credentials if you keep it private.

2. 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 names — you'll need them below.

3. Get the Gitea DB password

In the TrueNAS UI: Apps → Installed Apps → Gitea → Edit → Database Configuration. The Postgres password is visible there.

4. Create the read-only DB user

Edit db/setup.sql to set a password for heatmap_ro, then run it against the DB container (name from step 2):

docker exec -i <gitea-db-container> psql -U gitea -d gitea < db/setup.sql

5. Install via the Custom App Wizard

In the TrueNAS UI: Apps → Discover Apps → Custom App.

Field	Value
Application Name	gitea-heatmap-sidecar
Image Repository	gitea.yourdomain.com/yourusername/gitea-heatmap-sidecar
Image Tag	latest
Pull Policy	Always (so updates are picked up on restart)

Under Environment Variables, add:

Name	Value
DATABASE_URL	postgres://heatmap_ro:PASSWORD@<gitea-db-container>:5432/gitea?sslmode=disable
ALLOWED_USERS	your Gitea username, lowercase
ALLOWED_ORIGIN	https://gitea.yourdomain.com

Under Networking, add the Gitea Docker network (from step 2) as an additional network so the sidecar can reach the DB container by name.

Under Port Forwarding, map host port 8080 → container port 8080 (or omit this entirely if you're routing via a reverse proxy on the same Docker network).

Leave everything else at defaults and click Install.

6. Reverse proxy

Expose the sidecar at a public HTTPS hostname. With Nginx Proxy Manager:

• Scheme: http, Forward hostname: gitea-heatmap-sidecar (container name), Port: 8080
• Enable SSL via Let's Encrypt

For Traefik or Caddy on the same Docker network, wire it up the same way.

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

8. 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 and didericis with your username.

Restart Gitea, hit the profile page in incognito, and the heatmap should populate.