Documentation

Self-hosting

Run Katagami with PostgreSQL and storage that you control.

Choose your storage

Production Compose starts only PostgreSQL and Katagami. It does not run MinIO. Point Katagami at an S3-compatible bucket that you operate.

cp .env.prod.example .env
chmod 600 .env
docker compose --env-file .env -f docker-compose.prod.yml up --build -d

The example uses an external MinIO service:

S3_ENDPOINT=https://minio.example.internal
S3_FORCE_PATH_STYLE=true

Use S3_FORCE_PATH_STYLE=false for AWS S3. The storage identity needs HeadBucket, CreateBucket, GetObject, and PutObject permissions. Katagami uses conditional object creation, so the provider must support If-None-Match: *.

Protect the service

The container binds the renderer to 127.0.0.1. Put a TLS reverse proxy and your own access policy in front of it when remote clients need access. Keep PostgreSQL private. Treat .env as a secret.

Upgrade safely

1. Back up PostgreSQL and the object-storage bucket.
2. Start one updated renderer.
3. Call GET /v1/templates and render a known template version.
4. Start more renderer replicas only after the first renderer loads successfully.

Schema migrations move forward only. A manifest and the objects it names are one durable unit, so restore both PostgreSQL and object storage together.