Lumen
82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# homelab-app-template
|
|
|
|
Scaffold for a new homelab alpha app that deploys to TrueNAS via Gitea Actions
|
|
and can be publicly hosted over HTTPS with one script. Encodes the proven
|
|
InspectFlow / CannaManage pattern so Work Lumen can onboard a project in minutes,
|
|
not days.
|
|
|
|
**Read first:** [`homelab-release-runbook.md`](../plans/homelab-release-runbook.md:1)
|
|
— the authoritative procedure and the **port/subdomain registry** (allocate your
|
|
ports there before touching configs).
|
|
|
|
---
|
|
|
|
## What's in the box
|
|
|
|
```
|
|
.gitea/workflows/deploy.yml push-to-main → build + run on TrueNAS
|
|
docker-compose.yml base: db + backend + frontend
|
|
docker-compose.truenas.yml homelab override: ports, secrets, db internal-only
|
|
frontend/src/app/api/backend/[...path]/route.ts ⭐ the auth-token proxy fix
|
|
.env.example secret names + how to generate them
|
|
```
|
|
|
|
You bring the actual app code (Spring backend in `backend/`, Next.js frontend in
|
|
`frontend/`). The template wires the deploy + auth + hosting plumbing only.
|
|
|
|
---
|
|
|
|
## Onboard a new project (local phase)
|
|
|
|
1. **Allocate** a frp remotePort + frontend/backend host ports + subdomain in the
|
|
registry (runbook §2). Next free frp port lives there.
|
|
|
|
2. **Substitute placeholders.** From the new repo root:
|
|
```bash
|
|
PROJECT=myapp
|
|
FRONTEND_PORT=3001 # unique LAN host port
|
|
BACKEND_PORT=8082 # unique LAN host port (or remove backend ports block)
|
|
SUBDOMAIN=myapp.plate-software.de
|
|
|
|
grep -rlZ '__PROJECT__\|__FRONTEND_PORT__\|__BACKEND_PORT__\|__SUBDOMAIN__' . \
|
|
| xargs -0 sed -i \
|
|
-e "s/__PROJECT__/$PROJECT/g" \
|
|
-e "s/__FRONTEND_PORT__/$FRONTEND_PORT/g" \
|
|
-e "s/__BACKEND_PORT__/$BACKEND_PORT/g" \
|
|
-e "s/__SUBDOMAIN__/$SUBDOMAIN/g"
|
|
```
|
|
|
|
3. **Set Gitea Actions secrets** (repo → Settings → Actions → Secrets):
|
|
`AUTH_SECRET`, `JWT_SECRET`, `DB_PASSWORD`. Generate:
|
|
```bash
|
|
for s in AUTH_SECRET JWT_SECRET DB_PASSWORD; do echo "$s=$(openssl rand -base64 32)"; done
|
|
```
|
|
|
|
4. **Push to `main`.** The instance-level act_runner on TrueNAS auto-deploys.
|
|
App is live at `http://192.168.188.119:$FRONTEND_PORT`. Done — you can stay
|
|
here for the whole early-alpha period.
|
|
|
|
## Go public (additive switch, when ready)
|
|
|
|
```bash
|
|
# DNS A-record $SUBDOMAIN → 82.165.206.45 must exist first.
|
|
./scripts/homelab-publish.sh $PROJECT $FRONTEND_PORT $FRP_REMOTE_PORT $SUBDOMAIN
|
|
```
|
|
(`homelab-publish.sh` lives in the pi_mcps repo `scripts/`.) Verify per runbook §5.
|
|
|
|
---
|
|
|
|
## Why this template exists
|
|
|
|
- **The auth fix.** `frontend/.../api/backend/[...path]/route.ts` injects the
|
|
Bearer token server-side via `auth()`. A static Next rewrite cannot do this and
|
|
silently breaks auth — the ~9-day CannaManage blocker. Never delete this file.
|
|
- **db is internal-only** (`ports: !override []`) — no LAN Postgres exposure.
|
|
- **Password rotation reconcile** in deploy.yml handles the persistent-volume
|
|
`POSTGRES_PASSWORD` gotcha.
|
|
- **Frontend verify** uses a container-loopback node probe (no transient
|
|
false-failures from host-port timing).
|
|
|
|
See the runbook for the full topology, auth gotchas (NextAuth v5 `auth()` vs
|
|
`getToken()`), and the Let's Encrypt CA pin.
|