Setup Wizard

The setup wizard (npx learnhouse@latest setup) is an interactive 6-step process that generates a complete Docker Compose deployment. 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. LearnHouse 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):
  • AI-enabled (recommended) — Uses pgvector/pgvector:pg16 for RAG and vector search features
  • Standard — Uses postgres:16-alpine, lighter footprint
  • 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:

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.

Release Channels

During setup you choose a release channel:

• Stable — Recommended for production
• Dev — Bleeding edge, latest features
• Custom — Specify an exact image tag