stack/scripts

Mosaic Stack Setup Scripts

Comprehensive setup wizard for Mosaic Stack, inspired by the Calibr setup pattern.

Quick Start

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

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:

./scripts/setup.sh \
  --non-interactive \
  --mode docker \
  --enable-sso \
  --bundled-authentik \
  --ollama-mode local

Dry Run

Preview changes without execution:

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