Installation with the setup wizard

The provisioning wizard is the recommended way to install Copula self-hosted. It lives in the Copula app and runs before any Space exists — it provisions a fresh server end to end and gives you back a ready Space URL.

Prerequisites: a server that meets the requirements and a license token.

Wizard steps

1. SSH — enter the host, SSH port (default 22), the SSH user, and the authentication method (password or private key).
2. License — paste the LICENSE_TOKEN you copied from the cabinet.
3. Env — configure the backend environment:
   • admin credentials first: ADMIN_USER and ADMIN_PASS;
   • then the model provider block;
   • then secrets: JWT_SECRET (exactly 128 hex characters) and ENCRYPTION_KEY (32 characters) — both can be prefilled and regenerated by the wizard;
   • advanced fields are optional.
4. Domain — choose an auto-generated inst-<slug>.copul4.com subdomain or bring a custom FQDN (its A record must already point at the server).
5. Pre-flight — the wizard runs SSH checks against the target host.
6. Progress — the deploy runs.

What the deploy does

The deploy pipeline executes these steps in order:

install_docker → dns_setup → render_compose → upload_files → pull_images
→ start_postgres → run_migrations → start_backend → start_proxy → await_health

start_postgres is skipped when an external database is configured.

What lands on the host

The stack is deployed to /root/copula:

• /root/copula/docker-compose.yml
• /root/copula/.env (file mode 0600)
• /root/copula/Caddyfile

Services:

Service	Image / role
copula-postgres	postgres:16-alpine — provisioned database mode only; data at /root/copula/data; not exposed to the host
copula-migrate	One-shot init job built from the copula-api image itself (migrate CLI at /usr/local/bin/migrate, migration files at /migrations); runs before the backend via depends_on: service_completed_successfully
copula-back	Published backend image; host port 8901 → ${BACKEND_PORT}; volumes /root/copula/workspace → /workspace, /root/copula/ssh → /root/.ssh, ./.env → /config/.env:ro, /var/run/docker.sock
copula-cocoindex	cocoindex/cocoindex-code:full — code-search daemon
copula-caddy	caddy:2.11.4-alpine — publishes ports 80/443, obtains a Let's Encrypt certificate for the instance domain automatically, reverse-proxies to copula-back

After the deploy

The wizard finishes with the space URL https://<domain>. Add that URL as a Space in the Copula app to start working.

The default model configuration for new installs is MODEL_PROVIDER=copula with MODEL_NAME=copula-base — the cabinet LLM router, which needs no API key (the license token is the credential). openrouter and custom providers are selectable in the Env step; see the environment variable reference.

Next step

Reverse proxy and TLS →