# 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.md#4-install-the-profile-template-override)
to install the template override into that directory and restart Gitea.