Self Hosting

Self-Hosting

Run ZizkaDB on your laptop or VPS with Docker or a native fallback when Docker is unavailable.

OSS quickstart (recommended)

Docker (recommended — matches production)

git clone https://github.com/Zizka-ai/ZizkaDB.git && cd ZizkaDB
bash scripts/quickstart.sh

One command: Docker stack (pre-built GHCR images when available) + db.why() demo + dashboard link.

Stack only:

bash scripts/setup-local.sh

Connect your agent: CONNECT.md

Requires Docker Desktop or OrbStack running in a native arm64 Terminal (not Rosetta on Apple Silicon).

Or manually:

cp .env.example infra/.env
docker compose -f infra/docker-compose.yml -f infra/docker-compose.dashboard.yml up -d

Native fallback (no Docker)

When container runtime is unavailable:

bash scripts/bootstrap-local.sh
bash scripts/restart-native-stack.sh

Stop native stack:

bash scripts/stop-native-stack.sh

Services

Service	Default URL
API	http://localhost:8000
Deep health	http://localhost:8000/health/deep
Swagger	http://localhost:8000/swagger
Dashboard	http://localhost:3001
Postgres	localhost:5432 (native) or internal (Docker)
Redis	localhost:6379 (native) or internal (Docker)
Qdrant	localhost:6333 (native) or internal (Docker)

Dashboard login (local)

1. Open http://localhost:3001/login
2. Click Open my dashboard → (dev mode, no email)
3. Create agents and keys like production

For local smoke testing, prefer npm run build && npx next start -p 3001 (used by restart-native-stack.sh). npm run dev requires Node 20+ (see dashboard/.nvmrc).

SDK connection

db = ZizkaDB(host="http://localhost:8000")

MCP:

"env": { "ZIZKADB_HOST": "http://localhost:8000" }

Validation

bash scripts/validate-selfhost-config.sh   # env + connectivity
bash scripts/smoke-test.sh               # health, log, optional search

Optional: seed drift/baseline test data with python scripts/seed-support-bot-events.py.

Integration tests (stack must be running):

ZIZKADB_RUN_INTEGRATION=1 .venv/bin/pytest -m integration core/tests/test_integration_selfhost.py -v

Production self-host

bash infra/deploy-production.sh   # backup first — never uses docker compose down -v
bash infra/deploy-selfhost.sh

Never docker compose down -v on a server with real users.

Local laptop reset only:

bash scripts/reset-local-db.sh

Configure in infra/.env:

• DATABASE_URL
• REDIS_URL
• QDRANT_URL
• JWT_SECRET / JWT_REFRESH_SECRET
• EMAIL_* for OTP login
• ENV=production (disables dev key bypass)
• Do not set DEV_API_KEY in production
• DEPLOYMENT_MODE=self_hosted — keep this set even in production. ENV=production alone doesn't distinguish a self-hosted install from managed cloud (both use it), so this separate flag is what makes plan-based entitlement checks (e.g. API key limits) resolve to the Self-Hosted plan instead of whatever is in users.plan.
• API_KEY_LIMITS_ENFORCED=true — enable per-plan API key caps (Pro: 3, Team: 10, Enterprise: 50). Default false; self-hosted installs are uncapped unless you set this.

Validate production config before deploy:

bash scripts/validate-selfhost-config.sh --production

Embeddings

Set OPENAI_API_KEY in infra/.env for semantic search, memory context, and drift embeddings. Logging and why() work without it.

Dashboard → Settings → choose embedding model (OpenAI platform key or bring your own).

Backups

bash infra/backup-postgres.sh
bash infra/backup-qdrant.sh

See Production-Deployment.md for restore steps.