serverAppConfigs/docs/Dankclaw/Postgres.md

Postgres

PostgreSQL is the database backend for Gitea. It runs on the same podman network as Gitea and holds the repository metadata, users, and issue data.

Host: Dankclaw — Docs: https://www.postgresql.org/docs

Facts

Item	Value
Image	docker.io/library/postgres:16-alpine
Port	5432 (internal only)
Data volume	bind mount at /var/lib/postgresql/data

Configuration

services:
  postgres:
    image: docker.io/library/postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: "${GITEA_DB_PASSWORD}"
      POSTGRES_DB: gitea
    volumes:
      - /opt/gitea/data/gitea-postgres:/var/lib/postgresql/data

Gitea Connection

Gitea reaches the database over the systemd-gitea network (quadlet-managed live, compose-managed after the full-stack deploy):

environment:
  DATABASE_TYPE: postgres
  DATABASE_HOST: gitea-postgres
  DATABASE_NAME: gitea
  DATABASE_USER: gitea
  DATABASE_PASSWD: "${GITEA_DB_PASSWORD}"

The live app.ini on the host overrides env vars. When you rename the database container, update its [database] HOST line. See Gitea Gotchas.

Migration

The live Gitea stack on Dankclaw already runs this image with the data at /opt/gitea/data/gitea-postgres. The migration keeps the bind mount in place; see Gitea.

Healthcheck

Use pg_isready:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U gitea"]
  interval: 30s
  timeout: 5s
  retries: 3

Gotchas

• The database password must match between the postgres service and Gitea's DATABASE_PASSWD; both come from the same .env variable.
• Do not change the Gitea SECRET_KEY or INTERNAL_TOKEN after migration — encrypted data becomes unreadable.
• Back up with pg_dump; see Gitea (knowledge base).

See Also

• Gitea
• Dankclaw Stack