diff --git a/README.md b/README.md index 9e05add..5245925 100644 --- a/README.md +++ b/README.md @@ -26,151 +26,10 @@ JSON, and let a custom profile template render the squares client-side. [this service] → SELECT FROM action WHERE act_user_id=? → JSON ``` -## Setup +## Docs -### 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 below. | -| `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. - -## 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 \ - --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 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//gitea-heatmap-sidecar -cd /mnt//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//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 printenv GITEA_CUSTOM -``` - -Then follow [step 4 of the main setup](#4-install-the-profile-template-override) -to install the template override into that directory and restart Gitea. +- [Local setup](docs/local-setup.md) +- [TrueNAS SCALE setup](docs/truenas.md) ## Op type reference diff --git a/docs/local-setup.md b/docs/local-setup.md new file mode 100644 index 0000000..56dece8 --- /dev/null +++ b/docs/local-setup.md @@ -0,0 +1,54 @@ +# 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 new file mode 100644 index 0000000..eac8883 --- /dev/null +++ b/docs/truenas.md @@ -0,0 +1,90 @@ +# 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 \ + --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 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//gitea-heatmap-sidecar +cd /mnt//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//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 printenv GITEA_CUSTOM +``` + +Then follow [step 4 of the local setup](local-setup.md#4-install-the-profile-template-override) +to install the template override into that directory and restart Gitea.