From 88bb9749a32568729467cb4d674fde92ed8231de Mon Sep 17 00:00:00 2001 From: didericis Date: Tue, 5 May 2026 16:31:16 -0400 Subject: [PATCH] Switch deployment to TrueNAS Custom App Wizard Removes docker-compose.example.yml and docs/local.md; rewrites docs/truenas.md around the Custom App Wizard flow (image push to Gitea registry, env vars entered in UI, network attachment). Custom catalog approach is not available in Electric Eel 24.10+. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 6 +-- docker-compose.example.yml | 36 ------------- docs/local.md | 54 ------------------- docs/truenas.md | 108 ++++++++++++++++++++++--------------- 4 files changed, 67 insertions(+), 137 deletions(-) delete mode 100644 docker-compose.example.yml delete mode 100644 docs/local.md diff --git a/README.md b/README.md index 6164ade..1d23309 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,10 @@ JSON, and let a custom profile template render the squares client-side. [this service] → SELECT FROM action WHERE act_user_id=? → JSON ``` -## Docs +## Setup -- [Local setup](docs/local.md) -- [TrueNAS SCALE setup](docs/truenas.md) +See [docs/truenas.md](docs/truenas.md) for the full TrueNAS SCALE setup guide +(Custom App Wizard + Gitea template override). ## Op type reference diff --git a/docker-compose.example.yml b/docker-compose.example.yml deleted file mode 100644 index 6805406..0000000 --- a/docker-compose.example.yml +++ /dev/null @@ -1,36 +0,0 @@ -# Example: drop into the same Docker network as your existing Gitea stack. -# Adjust GITEA_DB_HOST, network name, and the reverse-proxy section to match -# your TrueNAS setup. - -services: - heatmap: - build: . - image: gitea-heatmap-sidecar:local - container_name: gitea-heatmap - restart: unless-stopped - environment: - # Read-only Postgres user (see db/setup.sql). - # Pass DATABASE_URL from the host environment — never write credentials to disk. - # e.g. export DATABASE_URL=postgres://heatmap_ro:...@gitea-db:5432/gitea?sslmode=disable - DATABASE_URL: - # Comma-separated lowercase usernames whose heatmap may be served. - ALLOWED_USERS: "didericis" - # CORS: must match the origin Gitea is served from. - ALLOWED_ORIGIN: "https://gitea.dideric.is" - # Optional: which Gitea action.op_type values count as a "contribution". - # Default 5,9,18 = commit push, tag push, mirror sync push. - # OP_TYPES: "5,9,11,18,24" - LISTEN: ":8080" - networks: - - gitea - healthcheck: - test: ["CMD", "/heatmap", "-healthcheck"] - interval: 30s - timeout: 5s - retries: 3 - start_period: 10s - -networks: - gitea: - # external: true # uncomment if your Gitea network already exists - name: gitea-net diff --git a/docs/local.md b/docs/local.md deleted file mode 100644 index 56dece8..0000000 --- a/docs/local.md +++ /dev/null @@ -1,54 +0,0 @@ -# Local setup - -### 1. Create a read-only Postgres user - -Run `db/setup.sql` against the Gitea database as a superuser. Edit the -password first. - -```bash -psql -U postgres -d gitea -f db/setup.sql -``` - -Only `SELECT` on `"user"` and `"action"` is granted. If Gitea ever renames -either table in a migration, the service will break loudly — that's the goal. - -### 2. Build and run the sidecar - -Edit `docker-compose.example.yml`, then: - -```bash -docker compose -f docker-compose.example.yml up -d --build -``` - -Make sure the `networks` block matches your existing Gitea Docker network so -the sidecar can reach `gitea-db` by hostname. - -Required env vars: - -| Var | Description | -|------------------|----------------------------------------------------------| -| `DATABASE_URL` | `postgres://heatmap_ro:...@host:5432/gitea?sslmode=...` | -| `ALLOWED_USERS` | Comma-separated lowercase usernames (e.g. `didericis`) | -| `ALLOWED_ORIGIN` | CORS origin — must match Gitea's URL | -| `OP_TYPES` | Optional. Comma-separated `op_type` ints. See README. | -| `LISTEN` | Optional. Default `:8080`. | - -### 3. Reverse proxy - -Expose the service at a hostname Gitea's frontend can reach over HTTPS — e.g. -`heatmap.dideric.is` → `heatmap:8080`. Use the same TLS setup as Gitea -itself (Caddy/Traefik/nginx). - -### 4. 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 -(e.g. `https://heatmap.dideric.is`) and `didericis` with the username you're -exposing. - -Restart Gitea, hit the profile page in incognito, and you should see the -heatmap populate. diff --git a/docs/truenas.md b/docs/truenas.md index ba31a93..f42cb62 100644 --- a/docs/truenas.md +++ b/docs/truenas.md @@ -1,9 +1,26 @@ # 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. +official app catalog. All shell commands run over SSH on the TrueNAS host. -### 1. Find Gitea's DB container and Docker network +## 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 @@ -14,77 +31,80 @@ docker inspect \ --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. +Note both names — you'll need them below. -### 2. Get the Gitea DB password +## 3. 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. +Configuration**. The Postgres password is visible there. -### 3. Create the read-only DB user +## 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: +the DB container (name from step 2): ```bash docker exec -i psql -U gitea -d gitea < db/setup.sql ``` -### 4. Clone and configure +## 5. Install via the Custom App Wizard -Put the repo somewhere on persistent storage: +In the TrueNAS UI: **Apps → Discover Apps → Custom App**. -```bash -git clone https://github.com/didericis/gitea-heatmap-sidecar \ - /mnt//gitea-heatmap-sidecar -cd /mnt//gitea-heatmap-sidecar -cp docker-compose.example.yml docker-compose.yml -``` +| 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) | -Edit `docker-compose.yml`: +Under **Environment Variables**, add: -- 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` +| Name | Value | +|------|-------| +| `DATABASE_URL` | `postgres://heatmap_ro:PASSWORD@:5432/gitea?sslmode=disable` | +| `ALLOWED_USERS` | your Gitea username, lowercase | +| `ALLOWED_ORIGIN` | `https://gitea.yourdomain.com` | -### 5. Build and start +Under **Networking**, add the Gitea Docker network (from step 2) as an +additional network so the sidecar can reach the DB container by name. -```bash -docker compose -f /mnt//gitea-heatmap-sidecar/docker-compose.yml up -d --build -``` +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). -Confirm it's healthy: +Leave everything else at defaults and click **Install**. -```bash -docker exec gitea-heatmap wget -qO- http://localhost:8080/healthz -``` +## 6. Reverse proxy -### 6. Reverse proxy +Expose the sidecar at a public HTTPS hostname. With **Nginx Proxy Manager**: -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), +- Scheme: `http`, Forward hostname: `gitea-heatmap-sidecar` (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. +For Traefik or Caddy on the same Docker network, wire it up the same way. -### 7. Find the Gitea custom directory +## 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: +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 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. +## 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.