prvng_platform/installer/README.md

# Provisioning Platform Installer

Interactive Ratatui-based installer for the Provisioning Platform with Nushell fallback for automation.

## 🎉 Implementation Status: COMPLETE

**All 7 UI screens fully implemented** (1,480 lines of code)
- ✅ Welcome Screen
- ✅ Platform Detection Screen
- ✅ Mode Selection Screen
- ✅ Service Selection Screen
- ✅ Configuration Wizard Screen
- ✅ Deployment Screen (with live progress)
- ✅ Completion Screen

**Status**: Ready for deployment logic integration and testing
**See**: [SCREENS_IMPLEMENTATION_STATUS.md](docs/SCREENS_IMPLEMENTATION_STATUS.md) for detailed implementation report

## Features

- 🎨 **Rich Interactive TUI** - Beautiful Ratatui interface with real-time feedback
- 🤖 **Headless Mode** - Automation-friendly with Nushell scripts
- 🚀 **One-Click Deploy** - Single command to deploy entire platform
- 🔧 **Platform Agnostic** - Supports Docker, Podman, Kubernetes, OrbStack
- 📊 **Live Progress** - Real-time deployment progress and logs
- ✅ **Health Checks** - Automatic service health verification

## Installation

### From Source

```bash
cd provisioning/platform/installer
cargo build --release
cargo install --path .
```

### Pre-built Binary

```bash
# Use the compiled binary directly
./provisioning/platform/installer/target/release/provisioning-installer
```

## Usage

### Interactive TUI (Default)

Just run the installer and follow the interactive prompts:

```bash
provisioning-installer
```

The TUI will guide you through:
1. Platform detection (Docker, Podman, K8s, OrbStack)
2. Deployment mode selection (Solo, Multi-User, CI/CD, Enterprise)
3. Service selection (check/uncheck services)
4. Configuration (domain, ports, secrets)
5. Live deployment with progress tracking
6. Success screen with access URLs

### Headless Mode (Automation)

For CI/CD pipelines and automation:

```bash
# Quick deploy with auto-detection
provisioning-installer --headless --mode solo --yes

# Fully specified
provisioning-installer \
  --headless \
  --platform orbstack \
  --mode solo \
  --services orchestrator,control-center,coredns \
  --domain localhost \
  --yes

# Use existing config file
provisioning-installer --headless --config my-deployment.toml --yes
```

### Configuration Generation

Generate configuration without deploying:

```bash
# TUI mode - generates config interactively
provisioning-installer --config-only

# Output saved to ~/.provisioning/installer-config.toml

# Deploy later with generated config
provisioning-installer --headless --config ~/.provisioning/installer-config.toml --yes
```

## Deployment Platforms

### Docker Compose

Standard Docker deployment with docker-compose:

```bash
provisioning-installer --platform docker --mode solo
```

**Requirements**: Docker 20.10+, docker-compose 2.0+

### OrbStack (macOS)

Optimized for macOS development:

```bash
provisioning-installer --platform orbstack --mode solo
```

**Requirements**: OrbStack installed, 4GB RAM, 2 CPU cores

### Podman (Rootless)

Secure rootless container deployment:

```bash
provisioning-installer --platform podman --mode solo
```

**Requirements**: Podman 4.0+, systemd (for user services)

### Kubernetes

Production-ready K8s deployment:

```bash
provisioning-installer --platform kubernetes --mode enterprise
```

**Requirements**: kubectl configured, Helm 3.0+ (optional)

## Deployment Modes

### Solo Mode (Development)

**Services**: 5 core services
**Resources**: 2 CPU cores, 4GB RAM, 20GB disk
**Use case**: Single developer, local testing

Services:
- Orchestrator
- Control Center
- CoreDNS
- OCI Registry (Zot)
- Extension Registry

### Multi-User Mode (Team)

**Services**: 7 services
**Resources**: 4 CPU cores, 8GB RAM, 50GB disk
**Use case**: Team collaboration, shared infrastructure

Additional services:
- Gitea (Git server)
- PostgreSQL (shared database)

### CI/CD Mode (Automation)

**Services**: 8-10 services
**Resources**: 8 CPU cores, 16GB RAM, 100GB disk
**Use case**: Automated pipelines, webhooks

Additional services:
- API Server
- Webhook handlers

### Enterprise Mode (Production)

**Services**: 15+ services
**Resources**: 16 CPU cores, 32GB RAM, 500GB disk
**Use case**: Production deployments, full observability

Additional services:
- Harbor OCI Registry
- Cosmian KMS
- Prometheus + Grafana
- Loki + Promtail
- Elasticsearch + Kibana
- Nginx reverse proxy

## CLI Options

```
provisioning-installer [OPTIONS]

OPTIONS:
  --headless              Run in headless mode (no TUI)
  --mode <MODE>           Deployment mode [solo|multi-user|cicd|enterprise]
  --platform <PLATFORM>   Target platform [docker|podman|kubernetes|orbstack]
  --services <SERVICES>   Comma-separated list of services
  --domain <DOMAIN>       Domain/hostname (default: localhost)
  --yes, -y               Skip confirmation prompts
  --config-only           Generate config without deploying
  --config <FILE>         Use existing config file
  -h, --help              Print help
  -V, --version           Print version
```

## Examples

### Quick Development Setup

```bash
# Interactive - best for first-time users
provisioning-installer

# Headless - for automation
provisioning-installer --headless --mode solo --yes
```

### Team Deployment with Gitea

```bash
provisioning-installer \
  --headless \
  --mode multi-user \
  --platform docker \
  --domain team.example.com \
  --yes
```

### Enterprise Production

```bash
provisioning-installer \
  --headless \
  --mode enterprise \
  --platform kubernetes \
  --domain provisioning.example.com \
  --config production.toml
```

### Custom Service Selection

```bash
provisioning-installer \
  --headless \
  --mode solo \
  --services orchestrator,control-center,coredns,mcp-server \
  --yes
```

## CI/CD Integration

### GitLab CI

```yaml
deploy_platform:
  stage: deploy
  script:
    - provisioning-installer --headless --mode cicd --platform kubernetes --yes
  only:
    - main
```

### GitHub Actions

```yaml
- name: Deploy Provisioning Platform
  run: |
    provisioning-installer --headless --mode cicd --platform docker --yes
```

## Nushell Scripts (Fallback)

If the Rust binary is unavailable, use Nushell scripts directly:

```bash
cd provisioning/platform/installer/scripts
nu deploy.nu --mode solo --platform orbstack --yes
```

## Development

### Build

```bash
cargo build
```

### Run

```bash
cargo run
```

### Test

```bash
cargo test
```

### Run in headless mode

```bash
cargo run -- --headless --mode solo --yes
```

## Troubleshooting

### Platform Not Detected

If your platform isn't detected automatically:

```bash
# Force specific platform
provisioning-installer --platform docker --yes
```

### Insufficient Resources

Check system resources:

```bash
# TUI will show warnings if resources are insufficient
provisioning-installer
```

Minimum requirements:
- Solo: 2 CPU, 4GB RAM
- Multi-User: 4 CPU, 8GB RAM
- CI/CD: 8 CPU, 16GB RAM
- Enterprise: 16 CPU, 32GB RAM

### Port Conflicts

Change default ports in config:

```bash
provisioning-installer --config-only
# Edit ~/.provisioning/installer-config.toml
# Change ports as needed
provisioning-installer --headless --config ~/.provisioning/installer-config.toml --yes
```

## Architecture

```
provisioning-installer
├── Interactive TUI (Ratatui)
│   ├── Welcome Screen
│   ├── Platform Detection
│   ├── Mode Selection
│   ├── Service Selection
│   ├── Configuration Wizard
│   ├── Live Deployment
│   └── Completion Screen
│
└── Headless Mode (Nushell scripts)
    ├── Platform Detection
    ├── Config Generation
    ├── Docker Deployment
    ├── Podman Deployment
    ├── Kubernetes Deployment
    └── OrbStack Deployment
```

## Related Documentation

- Main Project README: `../../README.md`
- Platform Deployment Guide: `../QUICK_START.md`
- Docker Compose Configs: `../docker-compose.yaml`
- Kubernetes Manifests: `../k8s/`

## License

Same as parent project.