z4jdev/z4j repository overview

⁠z4j

Open-source control plane for Python task infrastructure - FastAPI backend + React dashboard in a single container.

One dashboard for every Python task engine: Celery, RQ, Dramatiq, Huey, arq, TaskIQ, APScheduler, or plain scripts. Self-hosted. Zero external dependencies in the default mode (bundled SQLite).

Links: PyPI⁠ - GitHub⁠ - Docs⁠ - Website⁠

⁠Quick start

Run with SQLite (bundled, zero-config):

docker run -d --name z4j -p 7700:7700 -v z4j-data:/data z4jdev/z4j
docker logs -f z4j

The container:

• Auto-generates Z4J_SECRET + Z4J_SESSION_SECRET on first boot and persists them to /data/secret.env (survives restarts).
• Runs Alembic migrations to head.
• Prints a one-time setup URL in the logs: http://localhost:7700/setup?token=...

Open that URL, create the admin, and you land on the dashboard.

⁠Production: with PostgreSQL

For multi-admin, high-throughput, or compliance-grade deployments, use PostgreSQL. The same image switches mode based on Z4J_DATABASE_URL:

docker run -d --name z4j \
  -p 7700:7700 \
  -v z4j-data:/data \
  -e Z4J_DATABASE_URL=postgresql+asyncpg://user:pass@postgres-host:5432/z4j \
  -e Z4J_SECRET=$(openssl rand -hex 48) \
  -e Z4J_SESSION_SECRET=$(openssl rand -hex 48) \
  -e Z4J_PUBLIC_URL=https://z4j.example.com \
  -e Z4J_ALLOWED_HOSTS='["z4j.example.com"]' \
  z4jdev/z4j:1.4.0

PostgreSQL unlocks horizontal scale-out (LISTEN/NOTIFY-based registry fan-out), range-partitioned events, and tsvector full-text search.

⁠Docker Compose (recommended)

The z4jdev/z4j repo⁠ ships ready-to-use compose files:

git clone https://github.com/z4jdev/z4j.git
cd z4j

# SQLite (evaluation / homelab):
docker compose up -d

# PostgreSQL (production):
docker compose -f docker-compose.postgres.yml up -d

# Add Caddy auto-HTTPS on top of either:
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

⁠Environment variables

Full reference (30+ additional tunables for rate limits, Argon2 cost, CORS, session cookies, etc.): https://z4j.dev⁠.

⁠Volumes

⁠What's inside

• Backend: FastAPI + SQLAlchemy 2.0 async (Python 3.14-slim-trixie base image)
• Dashboard: React 19 + TanStack Start + Tailwind CSS 4, served from the same process at /
• Migrations: Alembic, auto-applied on first boot, bundled inside the image
• Database: SQLite (via aiosqlite) bundled by default; PostgreSQL 18 supported via Z4J_DATABASE_URL

Image size: ~234 MB uncompressed / ~52 MB compressed on-wire.

⁠Platform support

Native multi-arch: linux/amd64 + linux/arm64. The same image manifest serves both, built on native GitHub runners (no QEMU emulation).

⁠Tags

• z4jdev/z4j:1.4.0 - version-pinned, recommended for production
• z4jdev/z4j:latest - always-current, convenient for evaluation

⁠License

AGPL-3.0-or-later. Commercial license available ([email protected]).

The z4j image (this control plane) is AGPL. All agent packages (z4j-core, z4j-celery, z4j-django, z4j-rq, etc. - the client libraries your application embeds) are Apache 2.0 and do not subject your application to the AGPL.

⁠Related

• pip install z4j⁠ - PyPI distribution (same content, for Python-native installs; AGPL)
• github.com/z4jdev⁠ - all public repos (z4j + agent packages + sites)