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/.
107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
---
|
|
type: reference
|
|
title: Gitea Management
|
|
description: Gitea container management, boot persistence, troubleshooting, upgrades, and backup procedures on dankclaw.
|
|
tags:
|
|
- gitea
|
|
- management
|
|
- quadlet
|
|
verified: 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
|
|
|
|
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 `/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|client-access]] — how client hosts authenticate (token + credential store)
|
|
- [[architecture|architecture]] — network topology
|
|
- [[data-persistence|data-persistence]] — backups
|
|
- [[containers|containers]] — quadlet reference
|