Setup Wizard

The setup wizard (zeka-learnhouse setup) is an interactive 6-step process that generates a complete Docker Compose deployment for ZəkaHouse. You can go back and edit any step before confirming.

Step 1 — Install Directory

Choose where the deployment files will be created.

Default: ./learnhouse
The directory is created if it doesn’t exist

Step 2 — Domain Configuration

Configure your hostname and HTTPS settings.

Domain: hostname or IP address (default: localhost)
HTTPS options (non-localhost only):
- Automatic SSL (recommended) — Uses Let’s Encrypt via Caddy. Requires a valid domain and ports 80/443.
- Manual SSL — You handle the reverse proxy or Cloudflare. ZəkaHouse runs on HTTP internally.
- No HTTPS — HTTP only (not recommended for production)
Port: Automatically set based on SSL choice (443 for auto SSL, 80 for HTTP)

Step 3 — Database & Redis

Choose local Docker containers or connect to external services.

PostgreSQL

Local Docker (recommended):
- Uses pgvector/pgvector:pg16 (PostgreSQL 16 with the pgvector extension, used for AI/RAG features when enabled)
- Password is auto-generated
External — Provide a connection string (postgresql://user:pass@host:5432/db). The wizard tests connectivity before proceeding.

Redis

Local Docker (recommended) — Uses redis:7.2.3-alpine
External — Provide a connection string. The wizard tests connectivity before proceeding.

Step 4 — Organization

Set your organization name (e.g., “My School”). This creates the initial organization in the database.

Step 5 — Admin Account

Create the first admin user with email and password (minimum 8 characters).

Step 6 — Optional Features

Enable any of the following integrations:

Feature	Required Configuration
AI (Gemini)	Gemini API key
Email (Resend)	Resend API key + system email address
Email (SMTP)	Host, port, username, password, TLS toggle + system email
S3 Storage	Bucket name, endpoint URL (optional for AWS)
Google OAuth	Client ID + Client Secret
Unsplash	Access Key

Confirmation

After completing all steps, the wizard shows a summary of your configuration. You can:

Proceed — Generate files and optionally start the deployment
Edit — Go back and change any step
Cancel — Abort without generating anything

Generated Files

After confirmation, the wizard creates:

{installDir}/
├── docker-compose.yml        # Service definitions
├── .env                      # All configuration variables
├── learnhouse.config.json    # CLI metadata
└── extra/
    ├── Caddyfile             # If auto-SSL enabled
    └── nginx.prod.conf       # If manual SSL or HTTP

Docker Services

Each deployment gets a unique 8-character ID for container and network isolation.

Service	Image	Purpose
`learnhouse-app-{id}`	`zeka-learnhouse:<version>` (built locally — see below)	Next.js + FastAPI application
`learnhouse-db-{id}`	`pgvector/pgvector:pg16`	PostgreSQL database
`learnhouse-redis-{id}`	`redis:7.2.3-alpine`	Redis cache
`learnhouse-caddy-{id}`	`caddy:2-alpine`	Reverse proxy with auto-SSL
`learnhouse-nginx-{id}`	`nginx:alpine`	Reverse proxy (no auto-SSL)

The wizard optionally starts the deployment and waits up to 3 minutes for the health check (/api/v1/health) to pass before showing your credentials and URL.

App Image

The ZəkaHouse app image isn’t published to a container registry. The database, Redis, and reverse-proxy images are pulled from their public registries, but the app image must already exist on the machine — build it from the repository’s root Dockerfile (see Quick Install).

The wizard picks the app image in this order:

--image <image>, if you pass it
The LEARNHOUSE_APP_IMAGE environment variable
The release channel you choose during setup:
- Stable — zeka-learnhouse:<version>, matching the CLI’s own version (recommended for production)
- Dev — zeka-learnhouse:dev

To move a deployment to a different image after setup, use zeka-learnhouse update --to <tag> — the image must already be built or tagged locally.

PreviousEnvironment Variables NextDevelopers