Frank
3713339ffc
Uncommitted machine/session edits (live config, models, docs drift) were blocking the merge of origin/main. Committed as-is to preserve them; the merge that follows resolves overlapping prose files toward upstream canonical, with local variants recoverable from this commit. Pre-merge copies also in .AGENTTRASH/pre-merge-2026-10-18/.
4.8 KiB
type, title, description, tags, verified
| type | title | description | tags | verified | |||
|---|---|---|---|---|---|---|---|
| reference | Gitea Management | Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw. |
|
2026-10-18 |
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 | /home/dank/Containers/gitea/env (mode 0600, GITEA_DB_PASSWORD) — quadlet EnvironmentFile |
| Gitea app config | /home/dank/Containers/gitea/data/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
- Pull latest images:
podman pull docker.io/gitea/gitea:latest(repeat per image) - Restart the stack:
systemctl --user stop gitea-server gitea-postgres && systemctl --user start gitea-postgres gitea-server - 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 /home/dank/Containers/gitea/data/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
- client-access — how client hosts authenticate (token + credential store)
- architecture — network topology
- data-persistence — backups
- containers — quadlet reference