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

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

Pre-built Binary

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

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:

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

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

provisioning-installer --platform docker --mode solo

Requirements: Docker 20.10+, docker-compose 2.0+

OrbStack (macOS)

Optimized for macOS development:

provisioning-installer --platform orbstack --mode solo

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

Podman (Rootless)

Secure rootless container deployment:

provisioning-installer --platform podman --mode solo

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

Kubernetes

Production-ready K8s deployment:

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

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

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

Team Deployment with Gitea

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

Enterprise Production

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

Custom Service Selection

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

CI/CD Integration

GitLab CI

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

GitHub Actions

- 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:

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

Development

Build

cargo build

Run

cargo run

Test

cargo test

Run in headless mode

cargo run -- --headless --mode solo --yes

Troubleshooting

Platform Not Detected

If your platform isn't detected automatically:

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

Insufficient Resources

Check system resources:

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

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.