Move setup guides into docs/
Splits local-setup and TrueNAS SCALE instructions into docs/local-setup.md and docs/truenas.md; README now links to both. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
didericis
@@ -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
|
[this service] → SELECT FROM action WHERE act_user_id=? → JSON
|
||||||
```
|
```
|
||||||
|
|
||||||
## Setup
|
## Docs
|
||||||
|
|
||||||
### 1. Create a read-only Postgres user
|
- [Local setup](docs/local-setup.md)
|
||||||
|
- [TrueNAS SCALE setup](docs/truenas.md)
|
||||||
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 <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 main setup](#4-install-the-profile-template-override)
|
|
||||||
to install the template override into that directory and restart Gitea.
|
|
||||||
|
|
||||||
## Op type reference
|
## Op type reference
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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 <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-setup.md#4-install-the-profile-template-override)
|
||||||
|
to install the template override into that directory and restart Gitea.
|
||||||
Reference in New Issue
Block a user