feat: Add comprehensive setup wizard foundation

Modeled after Calibr setup.sh pattern (~/src/calibr/scripts/setup.sh). Implemented (Foundation): - Platform detection (Ubuntu, Arch, macOS, Fedora) - Dependency checking and installation - Mode selection (Docker vs Native) - Interactive + non-interactive modes - Comprehensive logging (clean console + full trace to log file) - Common utility functions library (450+ lines) Features in common.sh: - Output formatting (colors, headers, success/error/warning) - User input (confirm, select_option) - Platform detection - Dependency checking (Docker, Node, pnpm, PostgreSQL) - Package installation (apt, pacman, dnf, brew) - Validation (URL, email, port, domain) - Secret generation (cryptographically secure) - .env file parsing and management - Port conflict detection - File backup with timestamps To Be Implemented (See scripts/README.md): - Complete configuration collection - .env generation with smart preservation - Port conflict detection - Password/secret generation - Authentik blueprint auto-configuration - Docker deployment execution - Post-install instructions Usage: ./scripts/setup.sh # Interactive ./scripts/setup.sh --help # Show options ./scripts/setup.sh --dry-run # Preview ./scripts/setup.sh --non-interactive # CI/CD Refs: Setup wizard issue (created) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 16:44:25 -06:00
parent 0eb3abc12c
commit fd93be6032
26 changed files with 1255 additions and 7491 deletions
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -0,0 +1,265 @@
+# Mosaic Stack Setup Scripts
+
+Comprehensive setup wizard for Mosaic Stack, inspired by the [Calibr setup pattern](https://github.com/noahwoltje/calibr).
+
+## Quick Start
+
+```bash
+# Interactive setup (recommended)
+./scripts/setup.sh
+
+# Non-interactive Docker with SSO
+./scripts/setup.sh --non-interactive --mode docker --enable-sso --bundled-authentik
+
+# Dry run to see what would happen
+./scripts/setup.sh --dry-run --mode docker
+```
+
+## Current Status
+
+**✅ Implemented (Foundation):**
+
+- Platform detection (Ubuntu, Arch, macOS)
+- Dependency checking (Docker, Node.js, pnpm, PostgreSQL)
+- Dependency installation
+- Mode selection (Docker vs Native)
+- Argument parsing
+- Comprehensive logging
+- Common utility functions library
+
+**🚧 To Be Implemented:**
+
+- Complete configuration collection (SSO, Ollama, MoltBot, URLs)
+- .env file generation with smart preservation
+- Port conflict detection
+- Password/secret generation
+- Authentik blueprint auto-configuration
+- Docker deployment execution
+- Post-install instructions
+
+See full implementation plan in [issue tracking](https://git.mosaicstack.dev/mosaic/stack/issues).
+
+## Files
+
+```
+scripts/
+├── setup.sh              # Main setup wizard (foundation complete)
+├── lib/
+│   ├── common.sh         # Utility functions (complete)
+│   └── docker.sh         # Docker-specific functions (TODO)
+└── templates/
+    └── .env.template     # Template for .env generation (TODO)
+```
+
+## Features
+
+### Platform Detection
+
+Automatically detects:
+
+- Operating system (Ubuntu, Arch, Fedora, macOS)
+- Package manager (apt, pacman, dnf, brew)
+- Installed dependencies
+
+### Dependency Management
+
+Checks and optionally installs:
+
+- **Docker mode:** Docker, Docker Compose
+- **Native mode:** Node.js 18+, pnpm, PostgreSQL
+
+### Interactive Mode
+
+User-friendly wizard with:
+
+- Color-coded output
+- Clear prompts and defaults
+- Yes/no confirmations
+- Numbered menu selections
+
+### Non-Interactive Mode
+
+Suitable for CI/CD:
+
+```bash
+./scripts/setup.sh \
+  --non-interactive \
+  --mode docker \
+  --enable-sso \
+  --bundled-authentik \
+  --ollama-mode local
+```
+
+### Dry Run
+
+Preview changes without execution:
+
+```bash
+./scripts/setup.sh --dry-run --mode docker
+```
+
+## Common Functions (lib/common.sh)
+
+### Output Functions
+
+- `print_header()` - Section headers
+- `print_success()` - Success messages (green ✓)
+- `print_error()` - Error messages (red ✗)
+- `print_warning()` - Warnings (yellow ⚠)
+- `print_info()` - Info messages (blue ℹ)
+- `print_step()` - Step indicators (cyan →)
+
+### User Input
+
+- `confirm()` - Yes/no prompts with defaults
+- `select_option()` - Numbered menu selection
+
+### Platform Detection
+
+- `detect_os()` - Detect operating system
+- `detect_package_manager()` - Detect package manager
+- `get_os_name()` - Human-readable OS name
+
+### Dependency Checking
+
+- `check_command()` - Check if command exists
+- `check_docker()` - Check Docker installation and daemon
+- `check_docker_compose()` - Check Docker Compose
+- `check_node()` - Check Node.js version
+- `check_pnpm()` - Check pnpm installation
+- `check_postgres()` - Check PostgreSQL
+
+### Package Installation
+
+- `get_package_name()` - Get package name for specific manager
+- `install_package()` - Install package via detected manager
+- `check_sudo()` - Check/request sudo access
+
+### Validation
+
+- `validate_url()` - Validate URL format
+- `validate_email()` - Validate email format
+- `validate_port()` - Validate port number (1-65535)
+- `validate_domain()` - Validate domain name
+
+### Secret Generation
+
+- `generate_secret()` - Cryptographically secure random (with special chars)
+- `generate_password()` - User-friendly password (alphanumeric only)
+- `mask_value()` - Mask sensitive values for display
+- `is_placeholder()` - Detect placeholder values
+
+### .env Management
+
+- `parse_env_file()` - Parse .env into associative array
+- `get_env_value()` - Get value from parsed env
+- `set_env_value()` - Set value in env array
+
+### File Operations
+
+- `backup_file()` - Create timestamped backup
+
+### Port Checking
+
+- `check_port_in_use()` - Check if port is in use
+- `suggest_alternative_port()` - Suggest alternative if conflict
+
+## Logging
+
+All output is logged to `logs/setup-YYYYMMDD_HHMMSS.log`:
+
+- Clean output to console
+- Full trace (set -x) to log file only
+- Errors and warnings to both
+
+## CLI Options
+
+```
+--non-interactive       Run without prompts (requires all options)
+--dry-run              Show what would happen without executing
+--mode MODE            Deployment mode: docker or native
+--enable-sso           Enable Authentik SSO (Docker mode only)
+--bundled-authentik    Use bundled Authentik server (with --enable-sso)
+--external-authentik URL  Use external Authentik server URL
+--ollama-mode MODE     Ollama mode: local, remote, disabled (default)
+--ollama-url URL       Ollama server URL (if remote)
+--enable-moltbot       Enable MoltBot integration
+--base-url URL         Mosaic base URL (e.g., https://mosaic.example.com)
+--help                 Show help
+```
+
+## Next Steps for Implementation
+
+### 1. Configuration Collection (High Priority)
+
+- [ ] URL and domain configuration
+- [ ] SSO setup (bundled vs external Authentik)
+- [ ] Ollama configuration (local/remote/disabled)
+- [ ] MoltBot toggle
+- [ ] Existing config detection and smart updates
+
+### 2. .env Generation (High Priority)
+
+- [ ] Create .env template
+- [ ] Generate passwords/secrets securely
+- [ ] Preserve existing non-placeholder values
+- [ ] Apply port overrides
+- [ ] Write .admin-credentials file
+
+### 3. Port Conflict Detection
+
+- [ ] Check: 3000, 3001 (web), 4000 (API), 5432 (PostgreSQL), 6379 (Valkey), 9000/9443 (Authentik)
+- [ ] Suggest alternatives automatically
+- [ ] Update .env with overrides
+
+### 4. Authentik Blueprint Auto-Configuration
+
+- [ ] Copy blueprint to authentik-blueprints/
+- [ ] Create docker-compose.authentik.yml overlay
+- [ ] Mount blueprint volume
+- [ ] Document post-install steps (initial setup, client secret)
+
+### 5. Deployment Execution
+
+- [ ] Docker: docker compose up -d
+- [ ] Native: pnpm install, database setup, migrations
+- [ ] Health checks
+
+### 6. Post-Install Instructions
+
+- [ ] Show URLs (web, API, Authentik)
+- [ ] Show credentials location
+- [ ] Next steps checklist
+- [ ] Troubleshooting tips
+
+### 7. Testing
+
+- [ ] Test on Ubuntu, Arch, macOS
+- [ ] Test interactive mode
+- [ ] Test non-interactive mode
+- [ ] Test dry-run mode
+- [ ] Test existing .env preservation
+- [ ] Test port conflict handling
+
+## Contributing
+
+When extending this setup script:
+
+1. Follow the Calibr pattern for consistency
+2. Add utility functions to `lib/common.sh`
+3. Keep main `setup.sh` focused on orchestration
+4. Test both interactive and non-interactive modes
+5. Update this README with new features
+
+## Reference
+
+Original pattern: `~/src/calibr/scripts/setup.sh` (1,327 lines)
+
+Key patterns to follow:
+
+- Comprehensive error handling
+- Clear user communication
+- Smart existing config detection
+- Secure secret generation
+- Dry-run capability
+- Both interactive and non-interactive modes