prvng_platform/installer/scripts/README.md

# Provisioning Platform Installer - Nushell Deployment Scripts

Comprehensive Nushell deployment scripts for the Provisioning Platform Installer, providing three deployment modes: interactive, headless, and unattended automation.

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Deployment Modes](#deployment-modes)
  - [Interactive Mode](#interactive-mode)
  - [Headless Mode](#headless-mode)
  - [Unattended Mode](#unattended-mode)
- [Platform Support](#platform-support)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [Integration](#integration)
- [Troubleshooting](#troubleshooting)

## Overview

The Nushell deployment scripts provide a flexible, automation-friendly way to deploy the Provisioning Platform across multiple container platforms and orchestrators. These scripts complement the Rust TUI installer and enable CI/CD integration.

### Architecture

```
┌─────────────────────────────────────────────────────┐
│                  Deployment Entry                    │
│  ┌──────────┐  ┌──────────┐  ┌─────────────────┐   │
│  │Interactive│  │ Headless │  │   Unattended    │   │
│  │   Mode   │  │   Mode   │  │      Mode       │   │
│  └─────┬────┘  └─────┬────┘  └────────┬────────┘   │
└────────┼─────────────┼────────────────┼─────────────┘
         │             │                │
         ▼             ▼                ▼
┌─────────────────────────────────────────────────────┐
│              Core Helper Functions                   │
│  • Prerequisites Check    • Config Validation        │
│  • Health Checks         • Rollback Management      │
│  • Secret Generation     • Manifest Creation        │
└─────────────────────────────────────────────────────┘
         │             │                │
         ▼             ▼                ▼
┌─────────────────────────────────────────────────────┐
│           Platform-Specific Deployers                │
│  ┌────────┐  ┌────────┐  ┌───────────┐  ┌────────┐ │
│  │ Docker │  │ Podman │  │Kubernetes │  │OrbStack│ │
│  └────────┘  └────────┘  └───────────┘  └────────┘ │
└─────────────────────────────────────────────────────┘
         │             │                │
         ▼             ▼                ▼
┌─────────────────────────────────────────────────────┐
│              Integration Layer                       │
│  • MCP Server      • REST API      • Webhooks       │
│  • Rust Installer  • Notifications • Monitoring     │
└─────────────────────────────────────────────────────┘
```

## Features

### Core Features

- **Three Deployment Modes**
  - Interactive TUI via Rust installer
  - Headless CLI for scripted deployments
  - Unattended automation for CI/CD

- **Multi-Platform Support**
  - Docker (docker-compose)
  - Podman (podman-compose)
  - Kubernetes (kubectl)
  - OrbStack (native macOS integration)

- **Robust Error Handling**
  - Prerequisites validation
  - Configuration validation
  - Health checks
  - Automatic rollback on failure

- **External Integrations**
  - MCP (Model Context Protocol) servers
  - REST APIs
  - Webhook notifications (Slack, Discord, Teams)
  - Deployment tracking

### Deployment Modes

#### Solo Mode
- **Target**: Single developer, local development
- **Services**: 3-7 services
- **Resources**: 2 CPU, 4GB RAM
- **Features**: Minimal setup, fast deployment

#### Multi-User Mode
- **Target**: Team collaboration
- **Services**: 7-9 services
- **Resources**: 4 CPU, 8GB RAM
- **Features**: Git server, shared database

#### CI/CD Mode
- **Target**: Automation pipelines
- **Services**: 8-10 services
- **Resources**: 8 CPU, 16GB RAM
- **Features**: API server, registry, automation

#### Enterprise Mode
- **Target**: Production deployments
- **Services**: 15+ services
- **Resources**: 16 CPU, 32GB RAM
- **Features**: Full observability, security, HA

## Prerequisites

### Required Tools

- **Nushell** >= 0.107.0 - Shell and scripting runtime
- **Docker** >= 20.10.0 - Container runtime (for Docker/OrbStack)
- **Podman** >= 3.0.0 - Container runtime (for Podman)
- **kubectl** >= 1.25.0 - Kubernetes CLI (for Kubernetes)
- **Git** >= 2.30.0 - Version control

### Optional Tools

- **podman-compose** - For Podman deployments
- **orb** - OrbStack CLI tools
- **glow** - Markdown rendering for help

### System Resources

Minimum resources depend on deployment mode:

| Mode | CPU Cores | Memory | Disk Space |
|------|-----------|--------|------------|
| Solo | 2 | 4GB | 10GB |
| Multi-User | 4 | 8GB | 20GB |
| CI/CD | 8 | 16GB | 50GB |
| Enterprise | 16 | 32GB | 100GB |

## Installation

### 1. Build Rust Installer

```bash
cd provisioning/platform/installer
cargo build --release
```

### 2. Verify Nushell Scripts

```bash
cd scripts
nu mod.nu
```

### 3. Run Prerequisites Check

```bash
nu -c "use mod.nu *; check-prerequisites"
```

## Deployment Modes

### Interactive Mode

**Best for**: First-time users, exploratory deployments

Launch the Rust TUI installer for guided configuration:

```bash
# Using Nushell
nu -c "use mod.nu *; deploy-interactive"

# Or directly
../target/release/provisioning-installer
```

**Features**:
- Step-by-step wizard
- Visual platform detection
- Service selection UI
- Real-time validation

### Headless Mode

**Best for**: Scripted deployments, known configurations

Deploy via command-line arguments without interactive prompts:

```bash
# Basic deployment
nu -c "use mod.nu *; deploy-headless docker solo"

# With custom domain
nu -c "use mod.nu *; deploy-headless kubernetes enterprise --domain prod.example.com"

# Specific services
nu -c "use mod.nu *; deploy-headless docker solo --services orchestrator,control-center,postgres"

# Auto-confirm
nu -c "use mod.nu *; deploy-headless podman cicd --auto-confirm"

# Config generation only
nu -c "use mod.nu *; deploy-headless docker solo --config-only"
```

**Parameters**:
- `platform`: docker | podman | kubernetes | orbstack
- `mode`: solo | multi-user | cicd | enterprise
- `--domain`: Custom domain (default: localhost)
- `--services`: Comma-separated service list
- `--auto-confirm`: Skip confirmation prompts
- `--config-only`: Generate config without deploying

### Unattended Mode

**Best for**: CI/CD pipelines, automated deployments

Fully automated deployment from configuration files:

```bash
# From TOML file
nu -c "use mod.nu *; deploy-unattended file ./configs/solo-example.toml"

# From MCP server
nu -c "use mod.nu *; deploy-unattended mcp http://mcp-server:8084/config"

# From REST API
nu -c "use mod.nu *; deploy-unattended api http://api.example.com/deployment/config"

# With webhook notifications
nu -c "use mod.nu *; deploy-unattended file ./configs/enterprise-example.toml --webhook-url http://hooks.slack.com/services/..."

# Strict validation
nu -c "use mod.nu *; deploy-unattended file ./config.toml --strict"
```

**Config Sources**:
- `file` - TOML configuration file
- `mcp` - MCP server endpoint
- `api` - REST API endpoint

**Options**:
- `--webhook-url`: Send progress notifications
- `--strict`: Enable strict validation (default: true)

## Platform Support

### Docker

Uses `docker-compose` with overlay files for different modes:

```bash
nu -c "use mod.nu *; deploy-headless docker solo"
```

**Requirements**:
- Docker Engine >= 20.10.0
- docker-compose (standalone or plugin)

**Compose Files**:
- Base: `docker-compose.yaml`
- Overlay: `docker-compose.{mode}.yaml`

### Podman

Uses `podman-compose` for rootless container deployment:

```bash
nu -c "use mod.nu *; deploy-headless podman multi-user"
```

**Requirements**:
- Podman >= 3.0.0
- podman-compose (pip install podman-compose)

**Features**:
- Rootless deployment
- Compatible with Docker Compose files

### Kubernetes

Generates and applies Kubernetes manifests:

```bash
nu -c "use mod.nu *; deploy-headless kubernetes enterprise --domain k8s.example.com"
```

**Requirements**:
- kubectl configured with cluster access
- Kubernetes >= 1.25.0

**Resources Created**:
- Namespace: `provisioning-platform`
- Deployments (one per service)
- Services (ClusterIP)
- ConfigMaps (for configuration)

### OrbStack

Uses OrbStack's optimized Docker on macOS:

```bash
nu -c "use mod.nu *; deploy-headless orbstack solo"
```

**Requirements**:
- OrbStack installed
- orb CLI tools enabled

**Benefits**:
- Fast container startup
- Native macOS integration
- Efficient resource usage

## Configuration

### TOML Configuration Format

```toml
# Platform and mode
platform = "docker"  # docker | podman | kubernetes | orbstack
mode = "solo"        # solo | multi-user | cicd | enterprise
domain = "localhost"
auto_generate_secrets = true

# Service configuration
[[services]]
name = "orchestrator"
description = "Task coordination"
port = 8080
enabled = true
required = true

[[services]]
name = "control-center"
description = "Web UI"
port = 8081
enabled = true
required = true
```

### Example Configurations

See `configs/` directory for examples:

- `solo-example.toml` - Solo developer setup
- `enterprise-example.toml` - Enterprise production setup

### Environment Variables

Generated `.env` file for Docker/Podman:

```bash
PROVISIONING_MODE=solo
PROVISIONING_DOMAIN=localhost
PROVISIONING_PLATFORM=docker
ORCHESTRATOR_PORT=8080
ORCHESTRATOR_ENABLED=true
CONTROL_CENTER_PORT=8081
CONTROL_CENTER_ENABLED=true
```

## Usage Examples

### Quick Start

```bash
# Interactive mode (recommended for first time)
nu -c "use mod.nu *; deploy-interactive"

# Solo development
nu -c "use mod.nu *; deploy-headless docker solo --auto-confirm"

# Team collaboration
nu -c "use mod.nu *; deploy-headless docker multi-user --domain team.local"
```

### CI/CD Integration

```yaml
# GitLab CI
deploy-provisioning:
  stage: deploy
  script:
    - cd provisioning/platform/installer/scripts
    - nu -c "use mod.nu *; deploy-unattended file ../config/cicd-deploy.toml --webhook-url $SLACK_WEBHOOK"
```

```yaml
# GitHub Actions
- name: Deploy Provisioning Platform
  run: |
    cd provisioning/platform/installer/scripts
    nu -c "use mod.nu *; deploy-unattended file ../config/prod-deploy.toml"
```

### Custom Service Selection

```bash
# Only orchestrator and control center
nu -c "use mod.nu *; deploy-headless docker solo --services orchestrator,control-center --auto-confirm"

# Full stack with all optional services
nu -c "use mod.nu *; deploy-headless docker solo --services orchestrator,control-center,coredns,oci-registry,extension-registry,mcp-server,api-gateway"
```

### Production Deployment

```bash
# Generate production config
nu -c "use mod.nu *; deploy-headless kubernetes enterprise --domain prod.acme.com --config-only"

# Review and customize config
vim configs/deployment_*.toml

# Deploy with strict validation
nu -c "use mod.nu *; deploy-unattended file configs/deployment_*.toml --strict --webhook-url https://hooks.slack.com/..."
```

## Integration

### MCP Server Integration

Load configuration from MCP server:

```bash
nu -c "use mod.nu *; deploy-unattended mcp http://mcp-server:8084/config"
```

MCP Request Format:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "config/get",
  "params": {
    "type": "deployment",
    "include_defaults": true
  }
}
```

### REST API Integration

Fetch deployment config from API:

```bash
nu -c "use mod.nu *; deploy-unattended api https://api.example.com/deployments/config"
```

Expected API Response:
```json
{
  "config": {
    "platform": "kubernetes",
    "mode": "enterprise",
    "domain": "k8s.example.com",
    "services": [...]
  }
}
```

### Webhook Notifications

Send deployment notifications to webhooks:

```bash
# Slack
nu -c "use mod.nu *; notify-slack 'https://hooks.slack.com/...' 'Deployment started' --color good"

# Discord
nu -c "use mod.nu *; notify-discord 'https://discord.com/api/webhooks/...' 'Deployment complete' --success"

# Microsoft Teams
nu -c "use mod.nu *; notify-teams 'https://outlook.office.com/webhook/...' 'Deployment' 'Success' --success"
```

### Calling Rust Installer

Deploy using Rust installer binary:

```bash
# Convert config to CLI args
nu -c "
use mod.nu *;
let config = load-config-from-file ./configs/solo-example.toml;
deploy-with-installer $config --auto-confirm
"
```

## Troubleshooting

### Prerequisites Check Failed

```bash
# Run diagnostics
nu -c "use mod.nu *; check-prerequisites"

# Install missing tools
# macOS
brew install nushell docker git

# Ubuntu/Debian
apt install nushell docker.io git
```

### Platform Not Available

```bash
# Check platform availability
nu -c "use mod.nu *; check-platform-availability docker"

# Verify platform is running
docker ps  # Docker
podman ps  # Podman
kubectl version  # Kubernetes
orb status  # OrbStack
```

### Health Checks Failed

```bash
# View service logs
docker-compose logs orchestrator  # Docker
podman-compose logs orchestrator  # Podman
kubectl logs -n provisioning-platform deployment/orchestrator  # Kubernetes

# Manual health check
curl http://localhost:8080/health
```

### Deployment Rollback

Automatic rollback on failure, or manual:

```bash
# Manual rollback
nu -c "
use mod.nu *;
let config = load-config-from-file ./configs/deployment_*.toml;
rollback-deployment $config
"

# Platform-specific
docker-compose down --volumes
podman-compose down --volumes
kubectl delete namespace provisioning-platform
```

### Configuration Validation

```bash
# Validate config file
nu -c "
use mod.nu *;
let config = load-config-from-file ./configs/my-config.toml;
validate-deployment-config $config --strict
"

# Check for errors
# - Missing required fields
# - Invalid platform/mode
# - Required services not enabled
```

## Module Reference

### Main Functions

| Function | Purpose |
|----------|---------|
| `deploy-interactive` | Launch TUI installer |
| `deploy-headless` | CLI deployment |
| `deploy-unattended` | Automated deployment |
| `deploy help` | Show usage help |

### Platform Functions

| Function | Purpose |
|----------|---------|
| `deploy-docker` | Docker deployment |
| `deploy-podman` | Podman deployment |
| `deploy-kubernetes` | Kubernetes deployment |
| `deploy-orbstack` | OrbStack deployment |

### Helper Functions

| Function | Purpose |
|----------|---------|
| `check-prerequisites` | Validate prerequisites |
| `validate-deployment-config` | Validate config |
| `check-deployment-health` | Run health checks |
| `rollback-deployment` | Rollback deployment |
| `generate-secrets` | Generate secrets |

### Integration Functions

| Function | Purpose |
|----------|---------|
| `load-config-from-mcp` | Load from MCP |
| `load-config-from-api` | Load from API |
| `notify-webhook` | Send webhook |
| `deploy-with-installer` | Use Rust installer |

## Best Practices

### 1. Use Configuration Files

Store deployment configs in version control:

```bash
# Bad
nu -c "use mod.nu *; deploy-headless docker solo --services svc1,svc2,svc3"

# Good
nu -c "use mod.nu *; deploy-unattended file ./configs/dev-deploy.toml"
```

### 2. Enable Strict Validation

Use `--strict` for production deployments:

```bash
nu -c "use mod.nu *; deploy-unattended file ./prod.toml --strict"
```

### 3. Use Webhooks for Monitoring

Get notified of deployment status:

```bash
nu -c "use mod.nu *; deploy-unattended file ./config.toml --webhook-url $WEBHOOK"
```

### 4. Test Before Production

Use `--config-only` to preview:

```bash
# Generate and review
nu -c "use mod.nu *; deploy-headless kubernetes enterprise --config-only"
vim configs/deployment_*.toml

# Deploy after review
nu -c "use mod.nu *; deploy-unattended file configs/deployment_*.toml"
```

### 5. Automated Health Checks

Always verify deployment health:

```bash
nu -c "
use mod.nu *;
let config = load-config-from-file ./config.toml;
check-deployment-health $config
"
```

## Contributing

Follow Nushell best practices from `.claude/best_nushell_code.md`:

- Single purpose functions
- Explicit type signatures
- Early validation and fail fast
- Pure functions (mark mutations with `!`)
- Comprehensive error handling

## License

Part of the Provisioning Platform project. See main LICENSE file.

## Support

- **Documentation**: See `docs/` directory
- **Issues**: Open GitHub issues
- **Community**: Join discussions

---

**Version**: 1.0.0
**Nushell**: >= 0.107.0
**Last Updated**: 2025-10-06