docs: rebuild KB in OKF v0.1 with live-verified facts

Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
2026-08-28 07:57:13 -07:00
1 parent 552d1ef8bf
commit 02883d3ed2
@@ -0,0 +1,88 @@
+---
+type: reference
+title: Gitea Architecture
+description: Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw.
+tags:
+  - gitea
+  - architecture
+  - unverified
+verified: 2026-08-28
+---
+
+# Gitea Architecture
+
+Three quadlet-managed containers on a shared private Podman network (rootless, user `dank`). Gitea connects to PostgreSQL via network DNS. Caddy proxies HTTP/S to Gitea.
+
+## Network Topology
+
+```
+Client (HTTPS)
+    ↓
+caddy :80/:443  (auto-TLS via Let's Encrypt DNS-01/Porkbun)
+    ↓ reverse_proxy 192.168.0.143:3000 (published quadlet port)
+gitea-server :3000  (web UI, API)
+    ↓ PostgreSQL protocol
+gitea-postgres :5432  (internal only)
+```
+
+## Network
+
+The containers share the quadlet network `systemd-gitea` (file `gitea.network`, DNS enabled by default). Container names resolve via network DNS.
+
+The automatic rootless `podman` default network has `dns_enabled: false`. Container names do not resolve there. Keep the Gitea stack on `systemd-gitea`.
+
+## Container and Unit Names
+
+| Container | Unit | Depends on |
+|---|---|---|
+| `gitea-postgres` | `gitea-postgres.service` | `gitea-network.service` |
+| `gitea-server` | `gitea-server.service` | `gitea-postgres.service` |
+
+Podman 5.x names quadlet units after the file (`gitea-server.service`), with no `container-` prefix.
+
+## Caddy Configuration
+
+Caddy is a separate quadlet-managed service (`caddy.container`) on the shared `dankclaw_default` network. The live Caddyfile at `/home/dank/Containers/caddy/Caddyfile` proxies Gitea via the published quadlet port:
+
+```
+gitea.franksdank.cloud {
+    reverse_proxy 192.168.0.143:3000
+}
+```
+
+- Caddy issues Let's Encrypt certs via DNS-01 (Porkbun module) — no inbound HTTP port needed.
+- Pi-hole quadlet resolves `gitea.franksdank.cloud` to `192.168.0.143` via `addn-hosts`.
+- Serves HTTP on port 80 and HTTPS on port 443, both bound to `0.0.0.0`.
+
+## Gitea Configuration
+
+Quadlet file: `~/.config/containers/systemd/gitea-server.container` (repo copy: `serverAppConfigs/dankclaw/gitea/quadlet/gitea-server.container`)
+
+Key environment variables:
+- `DATABASE_TYPE=postgres`
+- `DATABASE_HOST=gitea-postgres` (network DNS)
+- `DATABASE_NAME=gitea`
+- `DATABASE_USER=gitea`
+- `DATABASE_PASSWD` from `/opt/gitea/.env` (mode 0600)
+- `USER_UID=1000`, `USER_GID=1000`
+
+Gitea writes `/data/gitea/conf/app.ini` on first start (host: `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini`). The `[database] HOST` and `PASSWD` lines in app.ini override the env vars. When you rename the database container, edit the `HOST` line in app.ini as well.
+
+## Ports
+
+| Service | Host Binding | Container Port | Access |
+|---|---|---|---|
+| Gitea HTTP | `0.0.0.0:3000` | 3000 | Web UI, API |
+| Gitea SSH | `0.0.0.0:2222` | 22 | Git clone/push via SSH |
+| PostgreSQL | `5432` (internal) | 5432 | Container-to-container only |
+
+Note: the full-stack repo compose (`dankclaw/compose.yaml`) maps Gitea HTTP to host port 3001. The live stack uses 3000. Align before the full-stack deploy.
+
+
+`gitea.franksdank.cloud` resolves to `192.168.0.143` via the Pi-hole quadlet's `addn-hosts`. Caddy obtains Let's Encrypt certs via DNS-01 (Porkbun module), which requires no inbound port reachability. LAN clients reach Gitea via `http://dankclaw:3000` (published quadlet port).
+
+## See Also
+
+- ](index.md) — index with management commands
+- [[management|management]] — operations, boot persistence, incident
+- [[data-persistence|data-persistence]] — volumes and backups
@@ -0,0 +1,69 @@
+---
+type: reference
+title: Gitea Data Persistence
+description: Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw.
+tags:
+  - gitea
+  - data
+  - unverified
+verified: 2026-08-28
+---
+
+# Gitea Data Persistence
+
+All data lives on host bind mounts under `/opt/gitea/data/`. Containers are ephemeral. Quadlet stops remove the container (`podman run --rm --replace`). The next start recreates it. Data survives.
+
+## Volume Layout
+
+| Host Path | Container Mount | Contents |
+|---|---|---|
+| `/opt/gitea/data/gitea-gitea/` | `/data` | Git repositories, avatars, attachments, LFS objects, `app.ini` |
+| `/opt/gitea/data/gitea-postgres/` | `/var/lib/postgresql/data` | PostgreSQL WAL, tables, indexes |
+
+## Ownership
+
+The bind-mount directories are owned by host user `dank` (UID 1000). Files that the containers create are owned by host UID/GID **100999** — the rootless ID mapping of container uid/gid 1000 (dank subuid range 100000-165535). User `dank` cannot write those files directly from the host.
+
+Edit container-owned files inside the container:
+
+```
+podman exec --user 1000 gitea-server sed -i 's/old/new/' /data/gitea/conf/app.ini
+```
+
+## Backup Strategy
+
+### Full backup (recommended)
+
+Tar the entire data directory. This captures Gitea repos and PostgreSQL data in one archive.
+
+```
+tar czf gitea-backup-$(date +%F).tar.gz -C /opt/gitea data/
+```
+
+### PostgreSQL-only backup
+
+Use `pg_dump` for a portable SQL dump. Useful for restoring to a different PostgreSQL version.
+
+```
+podman exec -e PGPASSWORD="$GITEA_DB_PASSWORD" gitea-postgres pg_dump -U gitea gitea > gitea-db-$(date +%F).sql
+```
+
+Set `PGPASSWORD` from `/opt/gitea/.env` (mode 0600).
+
+### Restore procedure
+
+1. Stop the stack: `systemctl --user stop gitea-server gitea-postgres`
+2. Restore data: `tar xzf backup.tar.gz -C /opt/gitea/`
+3. Start the stack: `systemctl --user start gitea-postgres gitea-server`
+
+## Data Growth
+
+- Git repositories grow with each commit and push. Monitor with `du -sh /opt/gitea/data/gitea-gitea/git/repositories/`.
+- PostgreSQL WAL files accumulate. VACUUM via `podman exec gitea-postgres psql -U gitea -c "VACUUM;"`.
+- Gitea's log files grow with usage.
+
+## See Also
+
+- ](index.md) — index with management commands
+- [[management|management]] — operations and boot persistence
+- [[architecture|architecture]] — network and ports
@@ -0,0 +1,65 @@
+# Gitea on dankclaw
+
+Private Git hosting on dankclaw. Three quadlet-managed containers in the rootless podman session of user `dank`: Gitea, PostgreSQL, Caddy.
+
+**Host:** dankclaw (71.227.227.172)
+**Config:** `~/.config/containers/systemd/gitea-{postgres,server,caddy}.container` + `gitea.network`
+**Local access:** `http://dankclaw:3000`
+**Domain:** `https://gitea.franksdank.cloud` (DNS pending)
+
+## Architecture
+
+| Container | Unit | Port | Purpose |
+|---|---|---|---|
+| `gitea-server` | `gitea-server.service` | 3000 (HTTP), 2222 (SSH) | Git web UI, API, SSH daemon |
+| `gitea-postgres` | `gitea-postgres.service` | 5432 (internal) | Database |
+| `gitea-caddy` | `gitea-caddy.service` | 80, 443 | Reverse proxy, auto-TLS |
+
+The containers share the private network `systemd-gitea` (quadlet `gitea.network`, DNS enabled). The automatic `podman` default network has DNS disabled; do not run the stack on it.
+
+## Management
+
+All commands run as `dank` on dankclaw.
+
+| Action | Command |
+|---|---|
+| Start all | `systemctl --user start gitea-postgres gitea-server gitea-caddy` |
+| Stop all | `systemctl --user stop gitea-caddy gitea-server gitea-postgres` |
+| Restart Gitea only | `systemctl --user restart gitea-server` |
+| Follow logs | `podman logs -f gitea-server` or `journalctl --user -u gitea-server -f` |
+| Check status | `systemctl --user status gitea-postgres gitea-server gitea-caddy` |
+
+## Data Persistence
+
+All data lives on host bind mounts under `/opt/gitea/data/`. Containers are ephemeral. Stopping a quadlet unit removes its container; the next start recreates it. Volumes survive.
+
+| Volume Path | Container Mount | Contents |
+|---|---|---|
+| `/opt/gitea/data/gitea-gitea/` | `/data` | Git repositories, app.ini, attachments |
+| `/opt/gitea/data/gitea-postgres/` | `/var/lib/postgresql/data` | PostgreSQL data files |
+| `/opt/gitea/data/caddy/data/` | `/root/.local/share/caddy` | Caddy configuration, TLS certs |
+
+See [[data-persistence|data-persistence]] for backup and restore.
+
+## Boot Persistence
+
+User-level linger is enabled for `dank`. The units start at host boot without a login. Each unit carries `[Install] WantedBy=default.target`; the podman generator applies it. The legacy podman-compose stack had no units and did not survive reboots (incident 2026-08-16).
+
+See [[management|management]] for boot persistence details and troubleshooting.
+
+## Repo Copies
+
+The quadlet files, Caddyfile, and `.env.example` are tracked in the `serverAppConfigs` repo under `dankclaw/gitea/`. The live password lives only in `/opt/gitea/.env` on the host (mode 0600).
+
+## See Also
+
+- [[architecture|architecture]] — network topology and ports
+- [[management|management]] — operations, upgrades, backups, incident log
+- [[data-persistence|data-persistence]] — volumes and backup strategy
+- [[containers|containers]] — quadlet reference
+
+  * [Gitea Architecture](architecture.md) — Gitea container architecture, network topology, and Caddy reverse proxy configuration on dankclaw.
+
+  * [Gitea Data Persistence](data-persistence.md) — Gitea data persistence, volume mounts, ownership, and backup strategy on dankclaw.
+
+  * [Gitea Management](management.md) — Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw.
@@ -0,0 +1,106 @@
+---
+type: reference
+title: Gitea Management
+description: Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw.
+tags:
+  - gitea
+  - management
+  - quadlet
+  - unverified
+verified: 2026-08-28
+---
+
+# Gitea Management
+
+All commands run as `dank` on dankclaw. The stack is quadlet-managed (since 2026-08-16). The legacy podman-compose file is retired to `/opt/gitea/.deprecated/`.
+
+## Daily Operations
+
+| Task | Command |
+|---|---|
+| Start all services | `systemctl --user start gitea-postgres gitea-server` |
+| Stop all services | `systemctl --user stop gitea-server gitea-postgres` |
+| Restart Gitea only | `systemctl --user restart gitea-server` |
+| Follow container logs | `podman logs -f gitea-server` |
+| Follow unit logs | `journalctl --user -u gitea-server -f` |
+| Check status | `systemctl --user status gitea-postgres gitea-server` |
+| Check health | `curl -s http://127.0.0.1:3000/api/v1/version` |
+
+Start the stack in order (postgres, server). The unit dependencies enforce the order when you start a single unit, but starting all three explicitly avoids surprises.
+
+## Boot Persistence
+
+| Setting | Value | Check |
+|---|---|---|
+| Quadlet units | `~/.config/containers/systemd/gitea-{postgres,server}.container`, `gitea.network` | `systemctl --user list-units 'gitea*'` |
+| Boot enablement | `[Install] WantedBy=default.target` in each file | `systemctl --user is-enabled gitea-server` (reports `generated`) |
+| User linger | enabled for `dank` | `loginctl show-user dank \| grep Linger` |
+
+At boot, systemd starts the user manager (linger), then `gitea-network.service`, then the containers in dependency order. No login session is required.
+
+After editing a quadlet file: run `systemctl --user daemon-reload`, then restart the affected units.
+
+## Config Files
+
+| File | Path |
+|---|---|
+| Quadlet units | `~/.config/containers/systemd/gitea-*.container`, `gitea.network` |
+| Secrets | `/opt/gitea/.env` (mode 0600, `GITEA_DB_PASSWORD`) |
+| Gitea app config | `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini` (container-owned, UID 100999) |
+
+Repo copies: `serverAppConfigs/dankclaw/gitea/` (quadlet files, `.env.example`). Copy edits to the target, then `daemon-reload` + restart.
+
+## Upgrades
+
+1. Pull latest images: `podman pull docker.io/gitea/gitea:latest` (repeat per image)
+2. Restart the stack: `systemctl --user stop gitea-server gitea-postgres && systemctl --user start gitea-postgres gitea-server`
+3. Verify startup: `podman logs -f gitea-server`
+
+Gitea handles database migrations automatically on startup. PostgreSQL version bumps require editing the image tag in `gitea-postgres.container`, then a dump/restore of the data (a fresh PostgreSQL does not read the old data directory format blindly).
+
+## Troubleshooting
+
+### Gitea cannot reach the database
+
+Check the `[database] HOST` line in `/opt/gitea/data/gitea-gitea/gitea/conf/app.ini`. It must be `gitea-postgres:5432`. app.ini overrides the `DATABASE_HOST` env var.
+
+Then check name resolution from the container:
+
+```
+podman exec gitea-server getent hosts gitea-postgres
+```
+
+If it fails, the containers are not on the `systemd-gitea` network. Check `podman inspect gitea-server --format '{{.NetworkSettings.Networks}}'`.
+
+### Files in the data directory are not writable
+
+Container-created files are owned by host UID 100999 (rootless ID mapping of container uid 1000). Edit them inside the container:
+
+```
+podman exec --user 1000 gitea-server vi /data/gitea/conf/app.ini
+```
+
+### Caddy 502s
+
+The upstream `gitea-server:3000` is down or unresolvable. Start `gitea-server`, check its logs, and verify `/home/dank/Containers/caddy/Caddyfile` references `192.168.0.143:3000`.
+
+### Container names do not resolve
+
+The automatic rootless `podman` network has DNS disabled. Run the stack on `systemd-gitea` (see `gitea.network`). If the network state goes stale after a reboot, restart the stack; recreate the network only if restarts do not help.
+
+## Incident Log
+
+### 2026-08-16: down for ~1 hour after unattended reboot
+
+`unattended-upgrades` rebooted dankclaw at 15:01. The legacy podman-compose stack had no systemd units. Rootless podman does not auto-start containers at boot without units. Gitea stayed down until a manual start at 16:02.
+
+Fix: migrated the stack to quadlet units with `[Install] WantedBy=default.target` and enabled user-level linger. Also fixed two latent bugs found during the migration: the live Caddyfile upstream name (`server` → `192.168.0.143:3000`) and the stale `HOST = postgres:5432` line in app.ini (→ `gitea-postgres:5432`).
+
+Verify the fix on the next host reboot.
+
+## See Also
+
+- ](index.md) — index
+- [[architecture|architecture]] — network topology
+- [[data-persistence|data-persistence]] — backups
+- [[containers|containers]] — quadlet reference