# gitea
Runbook for the self-hosted git server at https://gitea.home.arpa.
Backing Postgres lives in the utility stack; Gitea itself sits in
`stacks/utility/`.
See also: mercemay.top/src/homelab-compose/
## Auth
Sign-in flows through Authelia via OIDC. The client is configured in
`stacks/auth/authelia/configuration.yml` under `identity_providers.oidc`.
## Paths
| path | purpose |
|-------------------------------------------|------------------------|
| /srv/homelab/stacks/utility/gitea/data | repos, LFS, attachments|
| /srv/homelab/stacks/utility/gitea/conf | app.ini |
| postgres: db `gitea` | metadata |
## Daily ops
- `docker compose -f stacks/utility/docker-compose.yml ps gitea`
- Logs: `docker logs gitea -n 200`
- Healthcheck: `curl -sk https://gitea.home.arpa/api/v1/version`
## Incident: repo push returns 500
1. Check postgres connectivity:
`docker exec gitea su -s /bin/sh git -c 'nc -z postgres 5432'`
2. Inspect the error in
`/srv/homelab/stacks/utility/gitea/data/log/gitea.log`.
3. If `pg_stat_activity` shows lock contention, restart:
`docker compose restart gitea`.
## Incident: SSH clone fails
Gitea SSH is served on 127.0.0.1:2222 and is port-forwarded from the
router only for TRUSTED VLAN clients. Verify:
- `ss -lntp | grep 2222` on the host.
- `ssh -p 2222 git@gitea.home.arpa -T` returns a banner.
## Backups
- Postgres dump via `backup/stages/pg-dump.sh` (db=gitea).
- Volumes tarred by `backup/stages/docker-volumes.sh` (volume
`homelab_gitea_data`).
Restore flow:
```
backup/restore/restore-from-b2.sh 20250128 pg
# then psql -U postgres gitea < gitea.sql
backup/restore/restore-from-b2.sh 20250128 vols
# copy extracted tree into place before starting gitea
```
## Upgrades
Gitea supports rolling forward only. Take a pg dump *before* pulling a
new image. If the schema migration fails, restore from that dump into
a fresh database.