jesus/prvng_platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
prvng_platform/installer/scripts/README.md
Jesús Pérez f2be2414e4 core: init repo and codebase
2025-10-07 10:59:52 +01:00

17 KiB
Raw Permalink Blame History

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

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

cd provisioning/platform/installer
cargo build --release

2. Verify Nushell Scripts

cd scripts
nu mod.nu

3. Run Prerequisites Check

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:

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

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

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

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:

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:

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:

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

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

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

# 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

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

# 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

# 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

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

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

MCP Request Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "config/get",
  "params": {
    "type": "deployment",
    "include_defaults": true
  }
}

REST API Integration

Fetch deployment config from API:

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

Expected API Response:

{
  "config": {
    "platform": "kubernetes",
    "mode": "enterprise",
    "domain": "k8s.example.com",
    "services": [...]
  }
}

Webhook Notifications

Send deployment notifications to webhooks:

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

# 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

# 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

# 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

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

# 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

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

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

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

3. Use Webhooks for Monitoring

Get notified of deployment status:

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

4. Test Before Production

Use --config-only to preview:

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

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