provisioning/docs/src/operations/installer-system.md

# Provisioning Platform Installer (v3.5.0)

## 🚀 Flexible Installation and Configuration System

A comprehensive installer system supporting interactive, headless, and unattended deployment modes with automatic configuration management via TOML
and MCP integration.

## Installation Modes

### 1. **Interactive TUI Mode**

Beautiful terminal user interface with step-by-step guidance.

```bash
provisioning-installer
```

**Features**:

- 7 interactive screens with progress tracking
- Real-time validation and error feedback
- Visual feedback for each configuration step
- Beautiful formatting with color and styling
- Nushell fallback for unsupported terminals

**Screens**:

1. Welcome and prerequisites check
2. Deployment mode selection
3. Infrastructure provider selection
4. Configuration details
5. Resource allocation (CPU, memory)
6. Security settings
7. Review and confirm

### 2. **Headless Mode**

CLI-only installation without interactive prompts, suitable for scripting.

```bash
provisioning-installer --headless --mode solo --yes
```

**Features**:

- Fully automated CLI options
- All settings via command-line flags
- No user interaction required
- Perfect for CI/CD pipelines
- Verbose output with progress tracking

**Common Usage**:

```bash
# Solo deployment
provisioning-installer --headless --mode solo --provider upcloud --yes

# Multi-user deployment
provisioning-installer --headless --mode multiuser --cpu 4 --memory 8192 --yes

# CI/CD mode
provisioning-installer --headless --mode cicd --config ci-config.toml --yes
```

### 3. **Unattended Mode**

Zero-interaction mode using pre-defined configuration files, ideal for infrastructure automation.

```toml
provisioning-installer --unattended --config config.toml
```

**Features**:

- Load all settings from TOML file
- Complete automation for GitOps workflows
- No user interaction or prompts
- Suitable for production deployments
- Comprehensive logging and audit trails

## Deployment Modes

Each mode configures resource allocation and features appropriately:

| Mode | CPUs | Memory | Use Case |
| ------ | ------ | -------- | ---------- |
| **Solo** | 2 | 4 GB | Single user development |
| **MultiUser** | 4 | 8 GB | Team development, testing |
| **CICD** | 8 | 16 GB | CI/CD pipelines, testing |
| **Enterprise** | 16 | 32 GB | Production deployment |

## Configuration System

### TOML Configuration

Define installation parameters in TOML format for unattended mode:

```toml
[installation]
mode = "solo"  # solo, multiuser, cicd, enterprise
provider = "upcloud"  # upcloud, aws, etc.

[resources]
cpu = 2000  # millicores
memory = 4096  # MB
disk = 50  # GB

[security]
enable_mfa = true
enable_audit = true
tls_enabled = true

[mcp]
enabled = true
endpoint = "http://localhost:9090"
```

### Configuration Loading Priority

Settings are loaded in this order (highest priority wins):

1. **CLI Arguments** - Direct command-line flags
2. **Environment Variables** - `PROVISIONING_*` variables
3. **Configuration File** - TOML file specified via `--config`
4. **MCP Integration** - AI-powered intelligent defaults
5. **Built-in Defaults** - System defaults

### MCP Integration

Model Context Protocol integration provides intelligent configuration:

**7 AI-Powered Settings Tools**:

- Resource recommendation engine
- Provider selection helper
- Security policy suggester
- Performance optimizer
- Compliance checker
- Network configuration advisor
- Monitoring setup assistant

```toml
# Use MCP for intelligent config suggestion
provisioning-installer --unattended --mcp-suggest > config.toml
```

## Deployment Automation

### Nushell Scripts

Complete deployment automation scripts for popular container runtimes:

```bash
# Docker deployment
./provisioning/platform/installer/deploy/docker.nu --config config.toml

# Podman deployment
./provisioning/platform/installer/deploy/podman.nu --config config.toml

# Kubernetes deployment
./provisioning/platform/installer/deploy/kubernetes.nu --config config.toml

# OrbStack deployment
./provisioning/platform/installer/deploy/orbstack.nu --config config.toml
```

### Self-Installation

Infrastructure components can query MCP and install themselves:

```bash
# Taskservs auto-install with dependencies
taskserv install-self kubernetes
taskserv install-self prometheus
taskserv install-self cilium
```

## Command Reference

```bash
# Show interactive installer
provisioning-installer

# Show help
provisioning-installer --help

# Show available modes
provisioning-installer --list-modes

# Show available providers
provisioning-installer --list-providers

# List available templates
provisioning-installer --list-templates

# Validate configuration file
provisioning-installer --validate --config config.toml

# Dry-run (check without installing)
provisioning-installer --config config.toml --check

# Full unattended installation
provisioning-installer --unattended --config config.toml

# Headless with specific settings
provisioning-installer --headless --mode solo --provider upcloud --cpu 2 --memory 4096 --yes
```

## Integration Examples

### GitOps Workflow

```bash
# Define in Git
cat > infrastructure/installer.toml << EOF
[installation]
mode = "multiuser"
provider = "upcloud"

[resources]
cpu = 4
memory = 8192
EOF

# Deploy via CI/CD
provisioning-installer --unattended --config infrastructure/installer.toml
```

### Terraform Integration

```bash
# Call installer as part of Terraform provisioning
resource "null_resource" "provisioning_installer" {
  provisioner "local-exec" {
    command = "provisioning-installer --unattended --config ${var.config_file}"
  }
}
```

### Ansible Integration

```bash
- name: Run provisioning installer
  shell: provisioning-installer --unattended --config /tmp/config.toml
  vars:
    ansible_python_interpreter: /usr/bin/python3
```

## Configuration Templates

Pre-built templates available in `provisioning/config/installer-templates/`:

- `solo-dev.toml` - Single developer setup
- `team-test.toml` - Team testing environment
- `cicd-pipeline.toml` - CI/CD integration
- `enterprise-prod.toml` - Production deployment
- `kubernetes-ha.toml` - High-availability Kubernetes
- `multicloud.toml` - Multi-provider setup

## Documentation

- **User Guide**: `user/provisioning-installer-guide.md`
- **Deployment Guide**: `operations/installer-deployment-guide.md`
- **Configuration Guide**: `infrastructure/installer-configuration-guide.md`

## Help and Support

```bash
# Show installer help
provisioning-installer --help

# Show detailed documentation
provisioning help installer

# Validate your configuration
provisioning-installer --validate --config your-config.toml

# Get configuration suggestions from MCP
provisioning-installer --config-suggest
```

## Nushell Fallback

If Ratatui TUI is not available, the installer automatically falls back to:

- Interactive Nushell prompt system
- Same functionality, text-based interface
- Full feature parity with TUI version