z4j + Postgres

Production

For Medium and larger businesses, regulated environments, compliance-sensitive teams

Two services. Same image. Horizontal-scale ready.

Small business Medium business Enterprise

Architecture

What runs: 2 services

z4j ships one image for the brain. Backend and dashboard are bundled. There is no separate frontend container.

1

z4j-brain

z4jdev/z4j:latest

Same image as the default. Bundles backend plus dashboard. Connects to external Postgres via Z4J_DATABASE_URL.

2

z4j-postgres

postgres:18-trixie

Your primary datastore. Holds events, tasks, schedules, users, HMAC-chained audit log, and partitioned event history.

Install

Get running in minutes

bash

# Two services. The z4j-brain image is the SAME one from the default
# compose file; it auto-switches to Postgres because Z4J_DATABASE_URL
# is set. No separate image, no custom build.

# Set your secrets in .env first:
#   POSTGRES_PASSWORD=<long random>
#   Z4J_SECRET=<openssl rand -hex 48>
#   Z4J_SESSION_SECRET=<openssl rand -hex 48>
#   Z4J_PUBLIC_URL=https://z4j.yourdomain.com
#   Z4J_ALLOWED_HOSTS=["z4j.yourdomain.com"]

docker compose -f docker-compose.postgres.yml up -d --build

# First-boot admin URL is in the brain logs.
docker compose -f docker-compose.postgres.yml logs -f z4j-brain

After the brain is running, open http://localhost:7700 and sign in.

Requirements

Docker Compose v2+ or Kubernetes
PostgreSQL 17 or newer (18+ recommended for 3x I/O improvements)
Reverse proxy with TLS (Caddy, nginx, Traefik) or cloud load balancer
Secrets management (env, Vault, Sealed Secrets, etc.)

Database

PostgreSQL 17+ (18.3+ recommended)

Scale envelope

1000+ agents, 5000+ events/second, multiple brain replicas behind a load balancer

Decision helper

Is this the right tier for you?

Use this when

Self-hosted production deployments with audit requirements
Central Postgres with point-in-time recovery already in place
Teams with dedicated infrastructure or platform engineering
Compliance regimes (SOC 2, HIPAA, ISO 27001) that require Postgres
Kubernetes stacks with a Helm chart on the roadmap

Not ideal when

You are evaluating. Start with the default compose, then migrate.
Single-developer homelab where Postgres is overkill

What ships

Capabilities in this tier

All 6 engines supported
All 3 framework adapters
Full dashboard UI
RBAC and audit log
HMAC wire protocol
Auto-migrations on boot
Horizontal brain replicas
Range partitioning on events
Full-text search (tsvector)
LISTEN/NOTIFY live updates

HTTPS

Put a TLS terminator in front

The brain image binds HTTP on port 7700. In production, route traffic through a reverse proxy that terminates TLS. z4j does not bundle one because your infrastructure likely already has one.

For a homelab with a public DNS name, the optional Caddy compose overlay shipped in the repo gives you auto-HTTPS via Let's Encrypt in about two minutes. Teams with existing Traefik, Cloudflare, or nginx plug z4j in with a few lines of config.

TLS setup guide

Upgrade path