cameleer-saas-installer/CLAUDE.md

Installer

Deployment Modes

The installer (install.sh) supports two deployment modes:

	Multi-tenant SaaS (DEPLOYMENT_MODE=saas)	Standalone (DEPLOYMENT_MODE=standalone)
Containers	traefik, postgres, clickhouse, logto, cameleer-saas	traefik, postgres, clickhouse, server, server-ui
Auth	Logto OIDC (SaaS admin + tenant users)	Local auth (built-in admin, no identity provider)
Tenant management	SaaS admin creates/manages tenants via UI	Single server instance, no fleet management
PostgreSQL	cameleer-postgres image (multi-DB init)	Stock postgres:16-alpine (server creates schema via Flyway)
Use case	Platform vendor managing multiple customers	Single customer running the product directly

Standalone mode generates a simpler compose with the server running directly. No Logto, no SaaS management plane, no bootstrap. The admin logs in with local credentials at /.

Compose templates

The installer uses static docker-compose templates in templates/. Templates are copied to the install directory and composed via COMPOSE_FILE in .env:

• docker-compose.yml — shared infrastructure (traefik, postgres, clickhouse)
• docker-compose.saas.yml — SaaS mode (logto, cameleer-saas)
• docker-compose.server.yml — standalone mode (server, server-ui)
• docker-compose.tls.yml — overlay: custom TLS cert volume
• docker-compose.monitoring.yml — overlay: external monitoring network

SMTP configuration

The installer prompts for SMTP settings in SaaS mode when the user opts in ("Configure SMTP for email verification?"). SMTP is required for self-service sign-up — without it, only admin-created users can sign in.

Env vars: SMTP_HOST, SMTP_PORT (default 587), SMTP_USER, SMTP_PASS, SMTP_FROM_EMAIL (default noreply@<PUBLIC_HOST>). Passed to the cameleer-logto container. The bootstrap script discovers the SMTP connector factory and creates the connector with Cameleer-branded email templates.

CLI args: --smtp-host, --smtp-port, --smtp-user, --smtp-pass, --smtp-from-email. Persisted in cameleer.conf for upgrades/reconfigure.

Registry configuration

The installer supports pulling images from a custom Docker registry via --registry. Default: gitea.siegeln.net/cameleer.

When a registry is configured, the installer writes *_IMAGE env vars to .env (e.g. TRAEFIK_IMAGE, POSTGRES_IMAGE, CAMELEER_IMAGE) which override the defaults baked into the compose templates. In SaaS mode, provisioning image refs (CAMELEER_SAAS_PROVISIONING_*IMAGE) are also set from the registry.

For private registries, pass --registry-user / --registry-token. The installer runs docker login before pulling images. Credentials are persisted in cameleer.conf for upgrades/reconfigure.

Env var naming convention

• CAMELEER_AGENT_* — agent config (consumed by the Java agent)
• CAMELEER_SERVER_* — server config (consumed by cameleer-server)
• CAMELEER_SAAS_* — SaaS management plane config
• CAMELEER_SAAS_PROVISIONING_* — "SaaS forwards this to provisioned tenant servers"
• SMTP_* — email delivery config for Logto (consumed by bootstrap, SaaS mode only)
• No prefix (e.g. POSTGRES_PASSWORD, PUBLIC_HOST) — shared infrastructure, consumed by multiple components

Development

This repo is used as a git submodule in cameleer-saas at installer/. The dev compose in cameleer-saas chains the production templates from this repo via COMPOSE_FILE — no duplication.

Fixes to compose templates go here, then git submodule update --remote installer in cameleer-saas propagates them to dev.