diff --git a/README.md b/README.md index 99cd86f..0316431 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,252 @@ -# cameleer-saas-installer +# Cameleer SaaS Installer -One-line installer for the Cameleer SaaS platform \ No newline at end of file +One-line installer for the [Cameleer](https://cameleer.io) observability platform. Deploys as Docker containers behind Traefik with automatic TLS, Logto OIDC, and multi-tenant provisioning. + +## Quick Start + +**Linux / macOS:** + +```bash +curl -fsSL https://registry.cameleer.io/cameleer/cameleer-saas-installer/raw/branch/main/get-cameleer.sh | bash +cd installer && ./install.sh +``` + +**Windows (PowerShell):** + +```powershell +irm https://registry.cameleer.io/cameleer/cameleer-saas-installer/raw/branch/main/get-cameleer.ps1 | iex +cd installer; .\install.sh +``` + +**Pin a version:** + +```bash +curl -fsSL .../get-cameleer.sh | bash -s -- --version=v1.0.0 +``` + +## Deployment Modes + +| | Multi-tenant SaaS | Standalone | +|---|---|---| +| **Containers** | Traefik, PostgreSQL, ClickHouse, Logto, Cameleer SaaS | Traefik, PostgreSQL, ClickHouse, Server, Server UI | +| **Auth** | Logto OIDC (platform admin + tenant users) | Local auth (built-in admin, no IdP) | +| **Tenants** | Create/manage multiple tenants via UI | Single server instance | +| **Use case** | Platform vendor managing customers | Single customer running the product | + +## Installation Modes + +| Mode | Flag | Description | +|------|------|-------------| +| Simple | *(default)* | 6 questions, sensible defaults | +| Expert | `--expert` | Configure everything | +| Silent | `--silent` | Fully automated, all values from CLI/env/config | + +## Upgrade / Reconfigure + +Re-running the installer on an existing installation presents a menu: + +``` +[1] Upgrade — pull new images, update compose, restart +[2] Reconfigure — re-run interactive setup, preserve data +[3] Reinstall — fresh install (destroys data volumes) +[4] Cancel +``` + +--- + +## Configuration Reference + +Settings can be provided via CLI flags, environment variables, config file (`cameleer.conf`), or interactive prompts. Priority (highest to lowest): + +1. CLI arguments +2. Environment variables +3. Config file (via `--config` or auto-detected) +4. Interactive prompts +5. Default values + +### Hostname & Protocol + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| Public hostname | `--public-host` | `PUBLIC_HOST` | `public_host` | auto-detected | +| Auth hostname | `--auth-host` | `AUTH_HOST` | `auth_host` | same as `PUBLIC_HOST` | +| Protocol | `--public-protocol` | `PUBLIC_PROTOCOL` | `public_protocol` | `https` | + +`PUBLIC_HOST` is the primary hostname for the platform. `AUTH_HOST` defaults to the same value (single-domain setup). Set a separate `AUTH_HOST` only if Logto runs on a dedicated domain. + +### Admin Credentials + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| Admin username | `--admin-user` | `SAAS_ADMIN_USER` | `admin_user` | `admin` | +| Admin password | `--admin-password` | `SAAS_ADMIN_PASS` | `admin_password` | auto-generated | + +In standalone mode, the env vars are `SERVER_ADMIN_USER` / `SERVER_ADMIN_PASS`. + +### TLS Certificates + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| TLS mode | `--tls-mode` | `TLS_MODE` | `tls_mode` | `self-signed` | +| Certificate file | `--cert-file` | `CERT_FILE` | `cert_file` | — | +| Private key file | `--key-file` | `KEY_FILE` | `key_file` | — | +| CA bundle | `--ca-file` | `CA_FILE` | `ca_file` | — | + +Set `--tls-mode=custom` and provide PEM-encoded certificate files. With `self-signed`, a certificate is auto-generated at install time. + +### Network Ports + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| HTTP port | `--http-port` | `HTTP_PORT` | `http_port` | `80` | +| HTTPS port | `--https-port` | `HTTPS_PORT` | `https_port` | `443` | +| Logto console port | `--logto-console-port` | `LOGTO_CONSOLE_PORT` | `logto_console_port` | `3002` | +| Logto console exposed | `--logto-console-exposed` | `LOGTO_CONSOLE_EXPOSED` | `logto_console_exposed` | `true` | + +HTTP traffic is auto-redirected to HTTPS. The Logto admin console is bound to `127.0.0.1` by default (localhost only). Set `--logto-console-exposed` to bind on all interfaces. + +### Database Passwords + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| PostgreSQL password | `--postgres-password` | `POSTGRES_PASSWORD` | `postgres_password` | auto-generated | +| ClickHouse password | `--clickhouse-password` | `CLICKHOUSE_PASSWORD` | `clickhouse_password` | auto-generated | + +Auto-generated passwords are stored in `credentials.txt` inside the install directory. + +### Docker + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| Docker socket | `--docker-socket` | `DOCKER_SOCKET` | `docker_socket` | `/var/run/docker.sock` | +| Compose project name | `--compose-project` | `COMPOSE_PROJECT` | `compose_project` | `cameleer-saas` | + +The Docker socket is required for tenant provisioning (SaaS mode) — the platform creates per-tenant server containers on demand. + +### Image Registry + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| Registry | `--registry` | `REGISTRY` | `registry` | `gitea.siegeln.net/cameleer` | +| Registry username | `--registry-user` | `REGISTRY_USER` | `registry_user` | — | +| Registry token | `--registry-token` | `REGISTRY_TOKEN` | `registry_token` | — | +| Image version | `--version` | `VERSION` | `version` | `latest` | + +For private registries, provide credentials and the installer runs `docker login` before pulling. The registry prefix is applied to all container images. + +### SMTP (SaaS Mode) + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| SMTP host | `--smtp-host` | `SMTP_HOST` | `smtp_host` | — | +| SMTP port | `--smtp-port` | `SMTP_PORT` | `smtp_port` | `587` | +| SMTP username | `--smtp-user` | `SMTP_USER` | `smtp_user` | — | +| SMTP password | `--smtp-pass` | `SMTP_PASS` | `smtp_pass` | — | +| From email | `--smtp-from-email` | `SMTP_FROM_EMAIL` | `smtp_from_email` | `noreply@` | + +SMTP is required for self-service sign-up (email verification codes). Without it, only admin-created users can sign in. + +### Monitoring + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| Monitoring network | `--monitoring-network` | `MONITORING_NETWORK` | `monitoring_network` | — | + +Specify an external Docker network name to attach containers for Prometheus scraping. Containers expose metrics via `prometheus.io/*` labels. + +### TLS Verification + +| Setting | CLI Flag | Env Var | Config Key | Default | +|---------|----------|---------|------------|---------| +| Node TLS reject | `--node-tls-reject` | `NODE_TLS_REJECT` | `node_tls_reject` | `0` (self-signed) / `1` (custom) | + +Controls `NODE_TLS_REJECT_UNAUTHORIZED` inside the Logto container. Set to `0` for self-signed certificates, `1` for production certificates from a trusted CA. + +--- + +## Auto-Generated Secrets + +These are generated automatically and never need to be set manually: + +| Secret | Env Var | Description | +|--------|---------|-------------| +| JWT signing secret | `CAMELEER_SERVER_SECURITY_JWTSECRET` | Shared secret for JWT token signing across provisioned tenant servers | +| Bootstrap token | `BOOTSTRAP_TOKEN` | Server initialization token (standalone mode only) | + +--- + +## Architecture + +``` + ┌─────────────────────────────────────┐ + │ Traefik :443 │ + │ TLS termination + path routing │ + └──────┬──────────────┬───────────────┘ + │ │ + /platform/* │ │ /* (catch-all) + │ │ + ┌──────▼──────┐ ┌─────▼──────────┐ + │ Cameleer │ │ Logto │ + │ SaaS :8080 │ │ OIDC :3001 │ + │ Vendor + │ │ Custom sign-in │ + │ Tenant UI │ │ Admin :3002 │ + └──────┬─────┘ └─────────────────┘ + │ + Docker API │ provisions per-tenant + │ + ┌──────▼──────────────────────┐ + │ /t/{slug}/* │ + │ cameleer-server + server-ui │ + │ (one pair per tenant) │ + └─────────────────────────────┘ +``` + +All services share a single hostname. Routing: + +| Path | Target | +|------|--------| +| `/platform/*` | Cameleer SaaS management plane | +| `/t/{slug}/*` | Per-tenant server dashboard | +| `/*` | Logto (sign-in, OIDC, experience API) | +| `/` | Redirect to `/platform/` | + +--- + +## Files + +| File | Purpose | +|------|---------| +| `get-cameleer.sh` | Bootstrap script (bash) — downloads installer files | +| `get-cameleer.ps1` | Bootstrap script (PowerShell) — downloads installer files | +| `install.sh` | Main installer — interactive or silent deployment | +| `templates/docker-compose.yml` | Base infrastructure (Traefik, PostgreSQL, ClickHouse) | +| `templates/docker-compose.saas.yml` | SaaS mode (Logto + management plane) | +| `templates/docker-compose.server.yml` | Standalone mode (server + UI) | +| `templates/docker-compose.tls.yml` | Overlay: custom TLS certificate volume | +| `templates/docker-compose.monitoring.yml` | Overlay: external monitoring network | +| `templates/traefik-dynamic.yml` | Traefik TLS certificate configuration | +| `templates/.env.example` | Documented environment variable template | + +--- + +## Silent Install Example + +```bash +./install.sh --silent \ + --public-host=app.example.com \ + --admin-user=admin \ + --admin-password=s3cret \ + --tls-mode=custom \ + --cert-file=/etc/ssl/cert.pem \ + --key-file=/etc/ssl/key.pem \ + --smtp-host=smtp.example.com \ + --smtp-user=noreply@example.com \ + --smtp-pass=mailpass \ + --registry=registry.example.com/cameleer \ + --registry-user=deploy \ + --registry-token=ghp_xxx +``` + +## License + +Proprietary. See [cameleer.io](https://cameleer.io) for licensing.