Frank
02883d3ed2
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.
89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
---
|
|
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
|