Setup Wizard

The Setup Wizard is a comprehensive one-time configuration system that guides you through connecting PrintStudio to your infrastructure. Access it at http://localhost:4321/setup on first run.

Overview

The wizard walks through six steps:

1. Welcome — overview of what will be configured
2. Database & Queue — PostgreSQL and Redis connection strings
3. Printer Discovery — auto-detect or manually add printers
4. Integrations — n8n, FDM Monster, Obico, InvenTree, OpenClaw
5. Commerce — Stripe keys and email provider
6. Review & Launch — generate .env and restart services

Step 1 — Welcome

No configuration here. The wizard checks your current .env state and shows which services are already configured. If you have a partial .env, previously configured sections will be pre-filled.

Step 2 — Database & Queue

Enter your connection strings:

DATABASE_URL=postgresql://postgres:password@localhost:5432/printstudio
REDIS_URL=redis://localhost:6379

The wizard tests both connections before allowing you to proceed. A green checkmark means the service is reachable and accepting connections.

Tip

Use docker-compose up -d to start Postgres and Redis locally before running the wizard. Both are included in docker-compose.yml.

Step 3 — Printer Discovery

The wizard auto-scans localhost and your local /24 subnet for:

• OctoPrint instances (port 80, 443, 5000)
• Moonraker instances (port 7125)
• Bambu Lab printers (MQTT + LAN API)

Discovered printers appear in a list. Click a printer to test the connection and enter credentials if required.

You can also add printers manually:

Field	Description
Name	Display name (e.g., “Voron 2.4 #1”)
Type	moonraker, octoprint, or bambu
URL	Base URL including port
API Key	Optional for Moonraker; required for OctoPrint

Caution

Bambu Lab printers on newer firmware require the LAN-only mode to be enabled in the printer’s network settings before they accept API connections.

Step 4 — Integrations

Configure optional ecosystem services:

Integration	Purpose	Required?
n8n	Workflow automation (order emails, alerts)	No
FDM Monster	Print farm management UI	No
Obico	AI print failure detection	No
Home Assistant	Smart home / sensor integration	No
InvenTree	Parts & inventory management	No
OpenClaw	AI agent gateway (WhatsApp/Telegram ops)	No

For each integration, the wizard tests the connection URL and API key before saving.

Step 5 — Commerce

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PUBLISHABLE_KEY=pk_live_...

# Email — choose one provider
RESEND_API_KEY=re_...
# OR
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=...

Note

For local development, use Stripe test keys (sk_test_...). The webhook secret must match the endpoint configured in your Stripe dashboard.

Step 6 — Review & Launch

The wizard shows a summary of all configured services and generates a .env file at the project root. It uses packages/core/src/setup/env-generator.ts internally.

After saving, restart the API for changes to take effect:

# If running with Docker
docker compose restart api

# If running with Bun directly
# Restart your `bun dev` process

API Endpoints

The Setup Wizard backend is at apps/print-ops-api/src/routes/setup.ts:

Endpoint	Description
GET /api/setup/status	Current configuration state
POST /api/setup/test-connection	Test a service connection
POST /api/setup/discover	Trigger network discovery
POST /api/setup/save	Save config and generate .env
GET /api/setup/health	Health check all configured services

Troubleshooting

Discovery finds nothing — The scanner only checks localhost and the first 10 IPs in your subnet for speed. Add printers manually if they’re outside that range.

“Connection refused” on Postgres — Ensure Docker containers are running: docker compose ps. The default port is 5432.

Stripe webhook fails — Use the Stripe CLI to forward webhooks locally: stripe listen --forward-to localhost:8787/webhooks/stripe