diff --git a/docs/superpowers/specs/2026-04-13-install-script-design.md b/docs/superpowers/specs/2026-04-13-install-script-design.md new file mode 100644 index 0000000..7a36c06 --- /dev/null +++ b/docs/superpowers/specs/2026-04-13-install-script-design.md @@ -0,0 +1,413 @@ +# Cameleer SaaS Install Script Design + +## Overview + +A professional installer for the Cameleer SaaS platform, distributed as two native scripts (`install.sh` for Linux, `install.ps1` for Windows). The installer downloads nothing — it embeds compose templates and generates all configuration from user input. All service initialization logic is baked into Docker images, configured via environment variables. + +Distribution model: `curl -sfL https://install.cameleer.io | bash` (Linux), `irm https://install.cameleer.io/windows | iex` (Windows). + +## Platform Simplification (Prerequisites) + +The current architecture uses 7 services with 10+ bind-mounted config files. This design consolidates everything into 5 services with zero bind mounts (except Docker socket and optional user-supplied TLS certs). + +### Image Consolidation + +| Image | Base | Bakes in | +|---|---|---| +| `cameleer-traefik` | `traefik:v3` | Static/dynamic Traefik config, cert generation entrypoint (`openssl`), self-signed cert logic | +| `cameleer-postgres` | `postgres:16-alpine` | `init-databases.sh` (creates `cameleer_saas`, `logto` databases) | +| `cameleer-clickhouse` | `clickhouse/clickhouse-server` | Init SQL (`CREATE DATABASE cameleer`), `clickhouse-users.xml`, `clickhouse-config.xml` (Prometheus metrics) | +| `cameleer-logto` | `ghcr.io/logto-io/logto` | Custom sign-in UI, bootstrap logic (app/user/role/scope creation), vendor seed (env-var gated). Replaces the separate `logto-bootstrap` init container. | +| `cameleer-saas` | `eclipse-temurin:21-jre-alpine` | Spring Boot app + React SPA (already exists, no changes) | + +All images published to `gitea.siegeln.net/cameleer/`. + +### Service Reduction + +| Before | After | +|---|---| +| traefik-certs (init container) | Merged into `cameleer-traefik` entrypoint | +| traefik | `cameleer-traefik` | +| postgres + bind-mounted init script | `cameleer-postgres` | +| clickhouse + 3 bind-mounted config files | `cameleer-clickhouse` | +| logto | `cameleer-logto` (with bootstrap) | +| logto-bootstrap (init container) | Merged into `cameleer-logto` entrypoint | +| cameleer-saas + bind-mounted UI | `cameleer-saas` | + +**Result: 7 services → 5 services. 10+ bind-mounted files → 0.** + +### Bootstrap Merge + +The `logto-bootstrap` init container logic moves into `cameleer-logto`'s entrypoint as an idempotent startup step: + +1. Logto starts and seeds its own database (`npm run cli db seed -- --swe`) +2. Entrypoint runs bootstrap logic (create apps, users, roles, scopes, branding) +3. Bootstrap checks for cached results in a Docker volume — skips if already done +4. Writes `logto-bootstrap.json` to shared volume +5. If `VENDOR_SEED_ENABLED=true`, creates vendor user and global role +6. Logto server starts normally + +The `cameleer-saas` service uses `depends_on: logto (healthy)` and reads bootstrap results from the shared volume on startup — same as today. + +## Installer Architecture + +### Distribution + +- Linux: `curl -sfL https://install.cameleer.io | bash` +- Windows: `irm https://install.cameleer.io/windows | iex` + +The scripts are self-contained. They embed docker-compose templates and generate all files locally. No secondary downloads. + +### Scripts + +- `install.sh` — Bash, targets Linux with Docker Engine +- `install.ps1` — PowerShell, targets Windows with Docker Desktop (WSL2 backend) + +Both implement identical logic and produce identical output. They share a config file format (`cameleer.conf`) so configurations are portable between platforms. + +### Prerequisites + +The installer checks (does not install) these prerequisites: + +- Docker Engine (Linux) or Docker Desktop (Windows) — minimum version TBD +- Docker Compose v2 (`docker compose` subcommand) +- `openssl` (Linux, for password generation) — PowerShell uses `[System.Security.Cryptography.RandomNumberGenerator]` +- Ports 80, 443, 3002 are free (or custom ports if specified) +- Docker socket accessible + +If any prerequisite is missing, the script prints a clear error message with a link to installation instructions and exits. + +## Installation Modes + +### Simple Mode (default) + +Asks 6 essential questions: + +1. Install directory (default: `./cameleer`) +2. Public hostname (auto-detected, default: `localhost`) +3. Admin username (default: `admin`) +4. Admin password (default: auto-generated) +5. Use custom TLS certificates? (default: no → self-signed) + - If yes: paths to cert.pem, key.pem, optional ca.pem +6. Connect to a monitoring network? (default: none) + +Everything else uses secure defaults. All passwords auto-generated. + +### Expert Mode (`--expert` or chosen at interactive prompt) + +Adds these options, grouped by category: + +**Credentials:** +- PostgreSQL password (default: generated) +- ClickHouse password (default: generated) +- Vendor account enable + username + password + +**Networking:** +- HTTP port (default: 80) +- HTTPS port (default: 443) +- Logto admin console port (default: 3002) + +**Docker:** +- Image version/tag (default: `latest`) +- Compose project name (default: `cameleer-saas`) +- Docker socket path (auto-detected) + +**TLS:** +- CA bundle path +- `NODE_TLS_REJECT_UNAUTHORIZED` setting + +**Logto:** +- Admin console external exposure (default: yes) + +### Silent Mode (`--silent`) + +No interactive prompts. Uses defaults plus overrides. + +**Config precedence:** CLI flags > environment variables > config file (`--config`) > defaults. + +## Configuration Reference + +| Config key | CLI flag | Env var | Default | Simple | Expert | +|---|---|---|---|---|---| +| `install_dir` | `--install-dir` | `CAMELEER_INSTALL_DIR` | `./cameleer` | yes | yes | +| `public_host` | `--public-host` | `PUBLIC_HOST` | auto-detect | yes | yes | +| `public_protocol` | `--public-protocol` | `PUBLIC_PROTOCOL` | `https` | no | yes | +| `admin_user` | `--admin-user` | `SAAS_ADMIN_USER` | `admin` | yes | yes | +| `admin_password` | `--admin-password` | `SAAS_ADMIN_PASS` | generated | yes | yes | +| `tls_mode` | `--tls-mode` | `TLS_MODE` | `self-signed` | yes | yes | +| `cert_file` | `--cert-file` | `CERT_FILE` | none | yes* | yes | +| `key_file` | `--key-file` | `KEY_FILE` | none | yes* | yes | +| `ca_file` | `--ca-file` | `CA_FILE` | none | no | yes | +| `monitoring_network` | `--monitoring-network` | `MONITORING_NETWORK` | none | yes | yes | +| `postgres_password` | `--postgres-password` | `POSTGRES_PASSWORD` | generated | no | yes | +| `clickhouse_password` | `--clickhouse-password` | `CLICKHOUSE_PASSWORD` | generated | no | yes | +| `http_port` | `--http-port` | `HTTP_PORT` | `80` | no | yes | +| `https_port` | `--https-port` | `HTTPS_PORT` | `443` | no | yes | +| `logto_console_port` | `--logto-console-port` | `LOGTO_CONSOLE_PORT` | `3002` | no | yes | +| `logto_console_exposed` | `--logto-console-exposed` | `LOGTO_CONSOLE_EXPOSED` | `true` | no | yes | +| `vendor_enabled` | `--vendor-enabled` | `VENDOR_ENABLED` | `false` | no | yes | +| `vendor_user` | `--vendor-user` | `VENDOR_USER` | `vendor` | no | yes | +| `vendor_password` | `--vendor-password` | `VENDOR_PASS` | generated | no | yes | +| `version` | `--version` | `CAMELEER_VERSION` | `latest` | no | yes | +| `compose_project` | `--compose-project` | `COMPOSE_PROJECT` | `cameleer-saas` | no | yes | +| `docker_socket` | `--docker-socket` | `DOCKER_SOCKET` | auto-detect | no | yes | +| `node_tls_reject` | `--node-tls-reject` | `NODE_TLS_REJECT` | `0` (self-signed) / `1` (custom) | no | yes | + +*\* Only asked in simple mode if the user chooses custom TLS.* + +### Config File Format (`cameleer.conf`) + +```ini +# Cameleer installation config +# Generated by installer v1.0.0 on 2026-04-13 + +install_dir=./cameleer +public_host=cameleer.example.com +public_protocol=https +admin_user=my-admin +version=1.0.0 +tls_mode=custom +https_port=443 +monitoring_network=prometheus +``` + +Plain `key=value`, `#` comments. Portable between Linux and Windows. + +## Auto-Detection + +The installer auto-detects sensible defaults: + +| Value | Linux | Windows | +|---|---|---| +| Public hostname | `hostname -f`, reverse DNS of primary IP, fallback `localhost` | `[System.Net.Dns]::GetHostEntry`, fallback `localhost` | +| Docker socket | `/var/run/docker.sock` | `//./pipe/docker_engine` | +| Port availability | `ss -tlnp` or `netstat` check on 80, 443, 3002 | `Test-NetConnection` on 80, 443, 3002 | +| Existing install | Check for `cameleer.conf` in install directory | Same | + +## Output Files + +The installer generates the following in the install directory: + +``` +./cameleer/ + docker-compose.yml # Generated from embedded template + .env # All service configuration + .env.bak # Snapshot of .env at install time + cameleer.conf # Installer config (for re-runs, cloning) + credentials.txt # All generated passwords in plain text + INSTALL.md # Tailored documentation + certs/ # Only if user supplies custom TLS certs + cert.pem + key.pem + ca.pem +``` + +### docker-compose.yml (generated) + +The compose file is generated from a template embedded in the script, with values substituted from the user's configuration. Key characteristics: + +- All services use `${VARIABLE}` references to `.env` +- No bind mounts except Docker socket and optional `certs/` directory +- Shared volumes: `pgdata`, `chdata`, `bootstrapdata`, `certs` +- Networks: `cameleer` (internal), `cameleer-traefik` (for dynamic tenant routing) +- Optional external `monitoring_network` with Prometheus labels on services +- Health checks on all services +- `depends_on` with health conditions for startup ordering + +### credentials.txt + +``` +=========================================== + CAMELEER PLATFORM CREDENTIALS + Generated: 2026-04-13 14:32:00 UTC + + SECURE THIS FILE AND DELETE AFTER NOTING + THESE CREDENTIALS CANNOT BE RECOVERED +=========================================== + +Admin Console: https://cameleer.example.com/platform/ +Admin User: my-admin +Admin Password: aB3x...generated...9Zq + +PostgreSQL: cameleer / Kx8m...generated...Wp2 +ClickHouse: default / Rm4n...generated...Ht7 + +Vendor User: acme-admin (not enabled) + +Logto Console: https://cameleer.example.com:3002 +``` + +Printed to terminal once at the end of installation. Never displayed again on re-runs. + +### INSTALL.md (generated) + +Tailored to the actual installation values. Sections: + +1. **Installation Summary** — version, date, mode, install directory +2. **Service URLs** — platform UI, Logto admin console, API endpoint +3. **First Steps** — log in as admin, create first tenant +4. **Architecture Overview** — containers running, purpose of each +5. **Networking** — ports, monitoring network, Docker networks +6. **TLS** — self-signed or custom, cert location, how to replace via vendor UI +7. **Data & Backups** — Docker volume names, backup commands (pg_dump, clickhouse-backup) +8. **Upgrading** — re-run installer with `--version`, what gets preserved +9. **Troubleshooting** — common issues with `docker compose logs` commands +10. **Uninstalling** — clean removal steps + +## Password Generation + +When no password is provided, the script generates cryptographically secure random passwords: + +- Linux: `openssl rand -base64 24` (32 characters) +- Windows: `[System.Security.Cryptography.RandomNumberGenerator]` → Base64 + +### Passwords Generated + +| Credential | Config key | Consumers | +|---|---|---| +| PostgreSQL password | `postgres_password` | postgres, logto, cameleer-saas | +| ClickHouse password | `clickhouse_password` | clickhouse, cameleer-saas (tenant provisioning) | +| Admin password | `admin_password` | Logto admin user | +| Vendor password | `vendor_password` | Logto vendor user (only if enabled) | + +### Credential Lifecycle + +1. Generated (or user-provided) during install +2. Written to `.env` (consumed by Docker Compose) +3. Written to `credentials.txt` in plain text +4. Printed to terminal once at end of installation +5. Never shown again — re-runs preserve existing credentials without displaying them + +## Monitoring Network Integration + +When a monitoring network is configured (simple or expert mode): + +1. The script verifies the network exists via `docker network inspect` + - If missing in interactive mode: asks whether to create it or skip + - If missing in silent mode: creates it automatically +2. The network is added as an external network in the generated `docker-compose.yml` +3. Services are attached to it and labeled for Prometheus Docker SD: + +```yaml +cameleer-saas: + labels: + prometheus.io/scrape: "true" + prometheus.io/port: "8080" + prometheus.io/path: "/platform/actuator/prometheus" + +cameleer-traefik: + labels: + prometheus.io/scrape: "true" + prometheus.io/port: "8082" + prometheus.io/path: "/metrics" + +cameleer-clickhouse: + labels: + prometheus.io/scrape: "true" + prometheus.io/port: "9363" + prometheus.io/path: "/metrics" +``` + +No Prometheus configuration needed on the customer's side — Docker service discovery picks up the labels automatically. + +## Idempotent Re-run & Upgrade + +### Detection + +The script checks for `cameleer.conf` in the install directory. If found, it's a re-run. + +### Interactive Re-run Menu + +``` +Existing Cameleer installation detected (v1.0.0) + Install directory: ./cameleer + Public host: cameleer.example.com + + [1] Upgrade to v1.1.0 (pull new images, update compose) + [2] Reconfigure (re-run interactive setup, preserve data) + [3] Reinstall (fresh install, WARNING: destroys data volumes) + [4] Cancel +``` + +### Re-run Behavior + +| Action | Preserve | Regenerate | Pull images | +|---|---|---|---| +| Upgrade | `.env`, `cameleer.conf`, `credentials.txt`, `certs/`, volumes | `docker-compose.yml`, `INSTALL.md` | yes (new version) | +| Reconfigure | Data volumes, `credentials.txt` (unless passwords changed) | `.env`, `docker-compose.yml`, `cameleer.conf`, `INSTALL.md` | optional | +| Reinstall | Nothing | Everything | yes | + +### Silent Re-run + +Defaults to upgrade. Override with `--reconfigure` or `--reinstall`. + +### Safety + +- Data volumes (`pgdata`, `chdata`, `bootstrapdata`) are never removed unless `--reinstall` is explicitly chosen +- `--reinstall` requires double opt-in: `--reinstall --confirm-destroy` +- The script never runs `docker volume rm` without this confirmation + +## Health Verification + +After `docker compose up -d`, the script polls services in dependency order: + +| Step | Service | Check | Timeout | +|---|---|---|---| +| 1 | PostgreSQL | `pg_isready` via `docker compose exec` | 120s | +| 2 | ClickHouse | `clickhouse-client` query via `docker compose exec` | 120s | +| 3 | Logto | GET `/oidc/.well-known/openid-configuration` | 120s | +| 4 | Bootstrap | Check `logto-bootstrap.json` exists in volume | 120s | +| 5 | Cameleer SaaS | GET `/platform/api/config` | 120s | +| 6 | Traefik | GET `https://{PUBLIC_HOST}/` (expect redirect) | 120s | + +**Polling interval:** 5 seconds. **Total timeout:** 5 minutes. + +### Output + +``` +Verifying installation... + [ok] PostgreSQL ready (3s) + [ok] ClickHouse ready (5s) + [ok] Logto ready (18s) + [ok] Bootstrap complete (0s) + [ok] Cameleer SaaS ready (8s) + [ok] Traefik routing ready (1s) + +Installation complete! +``` + +### Failure + +- Failing service marked with `[FAIL]` and a hint (e.g., "check `docker compose logs logto`") +- Remaining checks skipped +- Stack left running for inspection +- Script exits with code 1 + +## Script Structure (both platforms) + +``` +main() + parse_args() + detect_existing_install() + if existing → show_rerun_menu() + check_prerequisites() + auto_detect_defaults() + select_mode() # simple / expert / silent + if interactive → run_prompts() + merge_config() # CLI > env > config file > defaults + validate_config() + generate_passwords() # for any not provided + if custom_certs → copy_certs() + generate_env_file() + generate_compose_file() + write_config_file() # cameleer.conf + docker_compose_pull() + docker_compose_up() + verify_health() + generate_credentials_file() + generate_install_doc() + print_credentials() + print_summary() +``` + +Each function has a direct equivalent in both bash and PowerShell. The logic, prompts, and output are identical across platforms.