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

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

```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 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):

```bash
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:

```bash
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.