cameleer/cameleer-saas
2
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity

Add install script design spec

Browse Source 
Defines a professional installer for the Cameleer SaaS platform with
dual native scripts (bash + PowerShell), three installation modes
(simple/expert/silent), and a platform simplification that consolidates
7 services into 5 by baking all init logic into Docker images.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
hsiegeln
2026-04-13 15:37:23 +02:00
parent c2ccf9d233
commit 16a2ff3174
1 changed files with 413 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

413
docs/superpowers/specs/2026-04-13-install-script-design.md Normal file
View File

@@ -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.