From 6bba20d887ba3fe60ecc5a757610efc7479f94b9 Mon Sep 17 00:00:00 2001 From: claude Date: Sat, 25 Apr 2026 13:04:37 +0200 Subject: [PATCH] docs: add CLAUDE.md for AI-assisted development context --- CLAUDE.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..00077af --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,55 @@ +# 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@`). 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.