didericis/gitea-heatmap-sidecar
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Switch deployment to TrueNAS Custom App Wizard

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
didericis
2026-05-05 16:31:16 -04:00
parent 8ec8df3827
commit 88bb9749a3
4 changed files with 67 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -3
View File
@@ -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 [this service] → SELECT FROM action WHERE act_user_id=? → JSON
``` ```
## Docs ## Setup
- [Local setup](docs/local.md) See [docs/truenas.md](docs/truenas.md) for the full TrueNAS SCALE setup guide
- [TrueNAS SCALE setup](docs/truenas.md) (Custom App Wizard + Gitea template override).
## Op type reference ## Op type reference
docker-compose.example.yml
-36
View File
@@ -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
docs/local.md
-54
View File
@@ -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.
docs/truenas.md
+64 -44
View File
@@ -1,9 +1,26 @@
# TrueNAS SCALE setup # TrueNAS SCALE setup
Tested on TrueNAS SCALE 24.10 (Electric Eel) with Gitea installed via the 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 ```bash
# List Gitea-related containers # List Gitea-related containers
@@ -14,77 +31,80 @@ docker inspect <gitea-app-container> \
--format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{end}}' --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{end}}'
``` ```
Note both the DB container name (typically ends in `-postgres` or `-db`) and Note both names — you'll need them below.
the network name — you'll need them in the steps below.
### 2. Get the Gitea DB password ## 3. Get the Gitea DB password
In the TrueNAS UI: **Apps → Installed Apps → Gitea → Edit → Database In the TrueNAS UI: **Apps → Installed Apps → Gitea → Edit → Database
Configuration**. The Postgres password is visible there. You'll use it in Configuration**. The Postgres password is visible there.
steps 3 and 4.
### 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 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 ```bash
docker exec -i <gitea-db-container> psql -U gitea -d gitea < db/setup.sql docker exec -i <gitea-db-container> 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 | Field | Value |
git clone https://github.com/didericis/gitea-heatmap-sidecar \ |-------|-------|
/mnt/<pool>/gitea-heatmap-sidecar | Application Name | `gitea-heatmap-sidecar` |
cd /mnt/<pool>/gitea-heatmap-sidecar | Image Repository | `gitea.yourdomain.com/yourusername/gitea-heatmap-sidecar` |
cp docker-compose.example.yml docker-compose.yml | 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. | Name | Value |
`postgres://heatmap_ro:PASSWORD@gitea-db-container-name:5432/gitea?sslmode=disable` |------|-------|
- Set `ALLOWED_USERS` and `ALLOWED_ORIGIN` | `DATABASE_URL` | `postgres://heatmap_ro:PASSWORD@<gitea-db-container>:5432/gitea?sslmode=disable` |
- Under `networks.gitea`, set `name` to the network name from step 1 and | `ALLOWED_USERS` | your Gitea username, lowercase |
uncomment `external: true` | `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 Under **Port Forwarding**, map host port `8080` → container port `8080`
docker compose -f /mnt/<pool>/gitea-heatmap-sidecar/docker-compose.yml up -d --build (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 ## 6. Reverse proxy
docker exec gitea-heatmap wget -qO- http://localhost:8080/healthz
```
### 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** - Scheme: `http`, Forward hostname: `gitea-heatmap-sidecar` (container name),
(a common TrueNAS app on the same Docker network):
- Scheme: `http`, Forward hostname: `gitea-heatmap` (the container name),
Port: `8080` Port: `8080`
- Enable SSL via Let's Encrypt - Enable SSL via Let's Encrypt
For Traefik or Caddy configured as TrueNAS apps, wire it up the same way — For Traefik or Caddy on the same Docker network, wire it up the same way.
the sidecar is reachable by container name on the shared network.
### 7. Find the Gitea custom directory ## 7. Find the Gitea custom directory
In the TrueNAS UI: **Apps → Installed Apps → Gitea → Edit → Storage**. In the TrueNAS UI: **Apps → Installed Apps → Gitea → Edit → Storage**.
Find the host path mapped to the Gitea data volume. The custom directory Find the host path mapped to the Gitea data volume. The custom directory is
Gitea reads templates from is the `custom/` subdirectory of that path — the `custom/` subdirectory of that path. Check the `GITEA_CUSTOM` env var in
check the `GITEA_CUSTOM` env var in the container if unsure: the container if unsure:
```bash ```bash
docker exec <gitea-app-container> printenv GITEA_CUSTOM docker exec <gitea-app-container> printenv GITEA_CUSTOM
``` ```
Then follow [step 4 of the local setup](local.md#4-install-the-profile-template-override) ## 8. Install the profile template override
to install the template override into that directory and restart Gitea.
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.