cameleer-saas-installer/README.md

# Cameleer SaaS Installer

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
bash -c "$(curl -fsSL https://registry.cameleer.io/cameleer/cameleer-saas-installer/raw/branch/main/get-cameleer.sh)"
```

**Windows (PowerShell):**

```powershell
irm https://registry.cameleer.io/cameleer/cameleer-saas-installer/raw/branch/main/get-cameleer.ps1 | iex
```

The bootstrap downloads the installer into `./installer/` and launches it immediately. The interactive prompts run in your terminal.

**Pin a version:**

```bash
bash -c "$(curl -fsSL .../get-cameleer.sh)" -- --version=v1.0.0
```

```powershell
& ([scriptblock]::Create((irm .../get-cameleer.ps1))) -Version v1.0.0
```

Any extra arguments are forwarded to `install.sh` / `install.ps1` (e.g. `--silent`, `--expert`, `--public-host=…`).

## 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 |
| Admin email | `--admin-email` | `SAAS_ADMIN_EMAIL` | `admin_email` | `<username>@<PUBLIC_HOST>` |

Email is the primary user identity in SaaS mode. All users — including the admin — must have an email address. If `SAAS_ADMIN_EMAIL` is not set, the bootstrap derives it from `<SAAS_ADMIN_USER>@<PUBLIC_HOST>`.

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.

### Email / SMTP

Email connector configuration (SMTP, SES, etc.) is managed at runtime via the vendor admin UI at `/vendor/email`. The installer does not configure email delivery.

Self-service registration is disabled by default and is enabled automatically when the admin configures an email connector.

### 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 and launches `install.sh` |
| `get-cameleer.ps1` | Bootstrap script (PowerShell) — downloads installer files and launches `install.ps1` |
| `install.sh` | Main installer (Linux / macOS) — interactive or silent deployment |
| `install.ps1` | Main installer (Windows PowerShell) — 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 \
  --registry=registry.example.com/cameleer \
  --registry-user=deploy \
  --registry-token=ghp_xxx
```

## License

Proprietary. See [cameleer.io](https://cameleer.io) for licensing.