homelab/postgres

Shared PostgreSQL

This directory contains a PostgreSQL 15 deployment draft for Authentik, Gitea, Netronome, and Penpot. It creates one database and one login role per service; it does not migrate existing data or change application connection settings.

Compatibility baseline

Service	Current application	Current standalone PostgreSQL	Common PostgreSQL 15
Authentik	2025.10.2	15	Supported (Authentik requires 14+)
Gitea	1.27.3	14	Supported (Gitea requires 12+)
Netronome	0.14.0	17	Validate in staging; upstream's example uses 17 but no 17-only feature is documented
Penpot	2.17.2	15	Supported by the official deployment

PostgreSQL 15 is the conservative common major. A major-version downgrade or change must use a logical dump/restore; changing only the image tag while keeping a data directory is not supported. Back up and migrate one application at a time, starting with Netronome because its current standalone deployment uses PostgreSQL 17.

For Compose, copy .env.example to .env, set all passwords, and start it with docker compose -f shared-compose.yaml up -d. This file is intentionally not named compose.yaml, so the repository deploy workflow does not start a second database accidentally. Applications that use this database must also join that external network and use homelab-postgres:5432.

For Kubernetes, create k8s/secrets.yaml from the example before applying the manifests. The k8s/active marker makes the normal deploy workflow include the namespace, StatefulSet, ConfigMap, and NetworkPolicy. Applications use postgres.database.svc.cluster.local:5432. Migrate each existing database with a tested logical dump/restore before switching an application. Do not reuse a PostgreSQL 14 or 17 data directory with PostgreSQL 15.