Jesús Pérez f2be2414e4 core: init repo and codebase

2025-10-07 10:59:52 +01:00

18 KiB

Raw Blame History

Configuration System Integration Guide

Version: 3.5.0 Date: 2025-10-06 Status: Production Ready ✅

📋 Overview

This guide explains how the complete configuration system integrates across the Provisioning Platform installer, MCP server, and Nushell deployment scripts.

System Components

┌─────────────────────────────────────────────────────────────┐
│                        User / AI Client                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
         ┌─────────────┴──────────────┐
         │                            │
    ┌────▼──────────┐          ┌─────▼────────────┐
    │   Installer   │◄────────►│   MCP Server     │
    │   (Rust/TUI)  │          │  (Settings API)  │
    └────┬──────────┘          └──────────────────┘
         │
         │ Load Config
         ▼
    ┌────────────────────┐
    │ Config Files       │
    │ (.toml/.yaml)      │
    └────┬───────────────┘
         │
         │ Execute Deployment
         ▼
    ┌────────────────────┐
    │ Nushell Deploy     │
    │ Scripts (.nu)      │
    └────┬───────────────┘
         │
         ▼
    ┌────────────────────┐
    │ Container Platform │
    │ (Docker/Podman/K8s)│
    └────────────────────┘

🚀 Quick Start

1. Interactive Installation (TUI)

# Launch interactive installer
cd provisioning/platform/installer
cargo run --release

# Or with binary
./target/release/provisioning-installer

Features:

Rich terminal UI with Ratatui
Platform auto-detection
Service selection with checkboxes
Live deployment progress
Configuration preview

2. Headless Installation (CLI)

# Headless with CLI arguments
provisioning-installer --headless \
    --mode solo \
    --platform docker \
    --domain localhost \
    --services "orchestrator,mcp-server,control-center"

Features:

No UI required
Suitable for scripts
Progress logging to stdout
Exit codes for automation

3. Unattended Installation (Config File)

# Full automation from config file
provisioning-installer --unattended \
    --config provisioning/config/installer-examples/solo.toml

# Example configs available:
# - solo.toml         # Solo developer setup
# - multi-user.toml   # Team collaboration
# - cicd.toml         # CI/CD automation
# - enterprise.toml   # Enterprise production

Features:

Zero user interaction
Configuration-driven
Webhook notifications
Automatic rollback on failure
CI/CD ready

📁 Configuration Files

Location Hierarchy

Template (copy and customize):

provisioning/config/installer-config.toml.template

Examples (ready to use):

provisioning/config/installer-examples/
├── solo.toml
├── multi-user.toml
├── cicd.toml
└── enterprise.toml

User config (optional):
```
~/.provisioning/installer.toml
```

Configuration Structure

[installer]
mode = "interactive"  # interactive | headless | unattended
version = "3.5.0"

[deployment]
platform = "docker"        # docker | podman | kubernetes | orbstack
mode = "solo"             # solo | multi-user | cicd | enterprise
domain = "localhost"

[services]
# Core services
orchestrator = { enabled = true, port = 8080 }
mcp_server = { enabled = true, port = 3000 }
control_center = { enabled = true, port = 8000 }

# Optional services
postgres = { enabled = false, port = 5432 }
gitea = { enabled = false, port = 3001 }

[resources]
min_cpu_cores = 2
min_memory_gb = 4.0

[unattended]
enabled = true
notification_webhook = "https://hooks.slack.com/..."

🔧 MCP Server Integration

The MCP server provides intelligent settings management through 7 API tools.

Available MCP Tools

1. installer_get_settings

Query complete or partial settings for installation.

Input:

{
  "query": "solo developer setup for docker"
}

Output:

{
  "platform": "docker",
  "mode": "solo",
  "services": ["orchestrator", "mcp-server", "control-center"],
  "resources": {
    "cpu": 2,
    "memory": 4096
  },
  "confidence": 0.95
}

2. installer_complete_config

Auto-fill missing configuration values.

Input:

{
  "config": {
    "deployment": {
      "mode": "cicd"
    }
  }
}

Output:

{
  "deployment": {
    "mode": "cicd",
    "platform": "docker",  // AI-recommended
    "domain": "localhost"
  },
  "services": {
    "orchestrator": { "enabled": true },
    "gitea": { "enabled": true },        // Auto-added for CI/CD
    "postgres": { "enabled": true }      // Dependency
  },
  "resources": {
    "min_cpu_cores": 8,    // Mode requirement
    "min_memory_gb": 16.0
  }
}

3. installer_validate_config

Validate complete configuration.

Input:

{
  "config": {
    "deployment": {
      "platform": "docker",
      "mode": "enterprise"
    },
    "resources": {
      "min_cpu_cores": 2  // Too low for enterprise
    }
  }
}

Output:

{
  "valid": false,
  "errors": [
    "Enterprise mode requires minimum 16 CPU cores, got 2"
  ],
  "warnings": [
    "Consider enabling monitoring for enterprise deployments"
  ]
}

4. installer_get_defaults

Get mode-specific defaults.

Input:

{
  "mode": "multi-user"
}

Output:

{
  "mode": "multi-user",
  "min_cpu_cores": 4,
  "min_memory_gb": 8.0,
  "recommended_services": [
    "orchestrator",
    "control-center",
    "mcp-server",
    "gitea",
    "postgres"
  ]
}

5. installer_platform_recommendations

AI-powered platform selection.

Output:

{
  "recommendations": [
    {
      "platform": "docker",
      "confidence": 0.95,
      "reason": "Detected and available",
      "version": "24.0.5"
    },
    {
      "platform": "orbstack",
      "confidence": 0.85,
      "reason": "Faster than Docker on macOS"
    }
  ],
  "detected": ["docker", "orbstack"],
  "unavailable": ["podman", "kubernetes"]
}

6. installer_service_recommendations

Service selection by mode.

Input:

{
  "mode": "cicd"
}

Output:

{
  "required": ["orchestrator", "mcp-server"],
  "recommended": ["gitea", "postgres", "harbor"],
  "optional": ["prometheus", "grafana", "loki"],
  "total_count": 9
}

7. installer_resource_recommendations

Resource optimization.

Input:

{
  "mode": "solo"
}

Output:

{
  "cpu_cores": 2,
  "memory_gb": 4.0,
  "disk_gb": 20.0,
  "rationale": "Minimum requirements for solo developer setup",
  "scaling_options": {
    "cpu": "Can scale up to 4 cores for better performance",
    "memory": "8GB recommended if running multiple services"
  }
}

🔄 Integration Workflows

Workflow 1: Interactive Installation with MCP Recommendations

sequenceDiagram
    User->>Installer: Launch TUI
    Installer->>Platform: Detect (Docker, Podman, etc.)
    Installer->>MCP Server: installer_platform_recommendations
    MCP Server-->>Installer: Recommended: Docker (95% confidence)
    Installer->>User: Show platforms with recommendation
    User->>Installer: Select Solo mode
    Installer->>MCP Server: installer_service_recommendations(solo)
    MCP Server-->>Installer: 7 services recommended
    Installer->>User: Show services with checkboxes
    User->>Installer: Confirm deployment
    Installer->>Nushell: Execute deploy-interactive
    Nushell-->>User: Deployment complete

Workflow 2: Unattended Installation with Config File

sequenceDiagram
    CI/CD->>Installer: --unattended --config cicd.toml
    Installer->>Config: Load cicd.toml
    Installer->>MCP Server: installer_validate_config
    MCP Server-->>Installer: Valid ✅
    Installer->>Nushell: Execute deploy-unattended
    Nushell->>Docker: Deploy services
    Nushell->>Health Checks: Verify all services
    Nushell->>Webhook: Send completion notification
    Webhook-->>Slack: Deployment succeeded 🎉

Workflow 3: Taskserv Self-Installation

sequenceDiagram
    User->>Self-Install: ./kubernetes/self-install.nu
    Self-Install->>MCP Server: installer_get_settings(kubernetes)
    MCP Server-->>Self-Install: Settings + Dependencies
    Self-Install->>Config Gen: Generate installer config
    Self-Install->>Installer: --unattended --config /tmp/k8s.toml
    Installer->>Nushell: deploy-unattended
    Nushell->>Platform: Deploy kubernetes + containerd + etcd
    Nushell-->>User: Installation complete

📦 Nushell Deployment Scripts

Location

provisioning/platform/installer/scripts/
├── deploy.nu           # Main deployment script
├── platforms.nu        # Platform-specific (Docker, Podman, K8s, OrbStack)
├── helpers.nu          # Validation, health checks, rollback
├── integration.nu      # MCP, API, webhooks
└── mod.nu             # Module exports

Usage

1. Interactive Deployment

use deploy.nu *

# Launch Rust TUI installer
deploy-interactive

2. Headless Deployment

use deploy.nu *

# CLI-based deployment
deploy-headless \
    --mode solo \
    --platform docker \
    --domain localhost \
    --services "orchestrator,mcp-server,control-center"

3. Unattended Deployment

use deploy.nu *

# Fully automated from config file
deploy-unattended \
    --config /path/to/config.toml \
    --webhook "https://hooks.slack.com/..."

4. Platform-Specific Deployment

use platforms.nu *

# Docker Compose deployment
deploy-docker \
    --config /path/to/config.toml \
    --check  # Dry-run first

# Kubernetes deployment
deploy-kubernetes \
    --config /path/to/config.toml \
    --context production  # kubectl context

5. MCP Integration

use integration.nu *

# Query MCP for settings
let settings = query-mcp-settings "solo developer setup"

# Complete partial config
let complete_config = complete-config-via-mcp {
    deployment: { mode: "cicd" }
}

# Validate config
let validation = validate-config-via-mcp $config

🧪 Testing

Test Interactive Installation

cd provisioning/platform/installer

# Build
cargo build --release

# Run
./target/release/provisioning-installer

# Test screens:
# 1. Welcome
# 2. Platform Detection
# 3. Mode Selection
# 4. Service Selection
# 5. Config Review
# 6. Deployment
# 7. Completion

Test Headless Installation

# Solo mode
provisioning-installer --headless \
    --mode solo \
    --platform docker \
    --domain test.local

# Dry-run
provisioning-installer --headless \
    --mode solo \
    --platform docker \
    --config-only

Test Unattended Installation

# From example config
provisioning-installer --unattended \
    --config provisioning/config/installer-examples/solo.toml

# With webhook
provisioning-installer --unattended \
    --config my-config.toml

Test MCP Tools

# Start MCP server
cd provisioning/platform/mcp-server
cargo run --release --bin provisioning-mcp-server

# In another terminal, test with MCP client
# (requires MCP client tool)

Test Nushell Scripts

cd provisioning/platform/installer/scripts

# Run tests
nu test-scripts.nu

# Test specific function
nu -c "use deploy.nu *; deploy-headless --mode solo --platform docker --domain test.local --check"

🔍 Troubleshooting

Issue: Config file not found

Error: Failed to load config from /path/to/config.toml

Solution:

# Check file exists
ls -l /path/to/config.toml

# Use absolute path
provisioning-installer --unattended --config $(pwd)/config.toml

# Or copy from examples
cp provisioning/config/installer-examples/solo.toml my-config.toml
provisioning-installer --unattended --config my-config.toml

Issue: Platform not detected

Error: No platforms detected

Solution:

# Check Docker is running
docker ps

# Check Podman is running
podman ps

# Check kubectl is configured
kubectl version --client

# Manual platform selection
provisioning-installer --headless --platform docker

Issue: Resource requirements not met

Error: Insufficient resources: need 4 cores, have 2

Solution:

Choose lower mode (e.g., solo instead of multi-user)

Override resource checks in config:

[resources]
min_cpu_cores = 2  # Lower requirement

Disable services to reduce load

Issue: MCP server not responding

Error: Failed to query MCP server

Solution:

# Check MCP server is running
curl http://localhost:3000/health

# Start MCP server
cd provisioning/platform/mcp-server
cargo run --release --bin provisioning-mcp-server

# Check logs
tail -f ~/.provisioning/logs/mcp-server.log

Issue: Webhook notifications failing

Error: Failed to send webhook notification

Solution:

Check webhook URL is correct

Verify network connectivity:

curl -X POST https://hooks.slack.com/... -d '{"text":"test"}'

Check webhook configuration in config.toml:

[unattended.notification]
webhook_url = "https://..."
retry_attempts = 3

📚 Configuration Reference

Complete Example (Enterprise)

[installer]
mode = "unattended"
version = "3.5.0"
auto_detect_platform = true
timeout_seconds = 600
dry_run = false

[deployment]
platform = "kubernetes"
mode = "enterprise"
domain = "provisioning.company.com"

[deployment.location]
type = "cloud"
provider = "aws"
region = "us-east-1"

[deployment.remote]
enabled = true
kubectl_context = "production"

[resources]
min_cpu_cores = 16
min_memory_gb = 32.0
min_disk_gb = 100.0

[resources.allocation]
strategy = "balanced"
cpu_limit_factor = 1.5
memory_limit_factor = 1.5

[services]
orchestrator = { enabled = true, port = 8080, replicas = 3 }
control-center = { enabled = true, port = 8000, replicas = 2 }
mcp-server = { enabled = true, port = 3000, replicas = 2 }
api-gateway = { enabled = true, port = 8081, replicas = 3 }
postgres = { enabled = true, port = 5432, replicas = 3 }
harbor = { enabled = true, port = 5000, replicas = 2 }
prometheus = { enabled = true, port = 9090, replicas = 2 }
grafana = { enabled = true, port = 3002, replicas = 2 }
loki = { enabled = true, port = 3100, replicas = 2 }

[secrets]
auto_generate = true
storage_backend = "kms"
sops_enabled = false

[secrets.kms]
provider = "aws"
key_id = "arn:aws:kms:us-east-1:123456789012:key/..."

[mcp]
enabled = true
mode = "http"
endpoint = "http://mcp-server:3000"

[mcp.tools]
enabled = ["settings", "deployment", "monitoring"]

[unattended]
enabled = true
validation_strict = true
rollback_on_error = true

[unattended.notification]
webhook_url = "https://hooks.slack.com/..."
retry_attempts = 3
retry_delay_seconds = 5

[advanced.network]
pod_cidr = "10.244.0.0/16"
service_cidr = "10.96.0.0/12"
ingress_enabled = true
load_balancer_enabled = true

[advanced.storage]
storage_class = "fast-ssd"
persistent_volume_size = "50Gi"
backup_enabled = true

[advanced.logging]
level = "info"
aggregation_enabled = true
retention_days = 30

[advanced.health_checks]
enabled = true
initial_delay_seconds = 30
period_seconds = 10
timeout_seconds = 5

[advanced.rollback]
enabled = true
checkpoint_interval_seconds = 60
max_checkpoint_age_hours = 24

🎯 Best Practices

1. Configuration Management

Use version control: Store config files in Git
Separate environments: dev.toml, test.toml, prod.toml
Template configs: Copy from examples, don't modify originals
Validate before deploy: Use --config-only to test configs

2. Security

Never commit secrets: Use KMS, SOPS, or environment variables
Enable auto-generate: Let installer generate secrets
Use TLS: Enable TLS for all services in production
Restrict access: Configure firewall rules and network policies

3. Deployment

Test in dev first: Always test configs in development
Use check mode: Run with --check before actual deployment
Enable rollback: Configure rollback_on_error = true
Monitor deployments: Use webhook notifications

4. Scaling

Start small: Begin with solo mode, scale to enterprise
Resource planning: Monitor usage, adjust resources accordingly
High availability: Use replicas for critical services
Load balancing: Enable for production deployments

📖 Additional Resources

Documentation

Installer README: provisioning/platform/installer/README.md
Unattended Mode: provisioning/platform/installer/UNATTENDED_MODE.md
Config System: provisioning/platform/installer/config/README.md
MCP Tools: provisioning/platform/mcp-server/SETTINGS_TOOLS_IMPLEMENTATION.md
Nushell Scripts: provisioning/platform/installer/scripts/README.md

Examples

Config Examples: provisioning/config/installer-examples/
Nushell Examples: provisioning/platform/installer/scripts/configs/
Self-Install Examples: provisioning/extensions/taskservs/kubernetes/self-install.nu

Support

Issues: https://github.com/provisioning/issues
Discussions: https://github.com/provisioning/discussions
Documentation: https://docs.provisioning.dev

✅ Completion Checklist

Use this checklist to verify your configuration system integration:

Installer compiles successfully
MCP server compiles successfully (simple binary)
All Nushell scripts validated with Nushell 0.107.1
Config template exists and documented
Example configs for all 4 modes created
Interactive installation tested
Headless installation tested
Unattended installation tested
MCP tools respond correctly
Webhook notifications working
Self-install script tested
Documentation complete
Integration guide reviewed

Congratulations! Your configuration system is fully integrated and ready for production use. 🎉

18 KiB Raw Blame History

Configuration System Integration Guide

📋 Overview

System Components

🚀 Quick Start

1. Interactive Installation (TUI)

2. Headless Installation (CLI)

3. Unattended Installation (Config File)

📁 Configuration Files

Location Hierarchy

Configuration Structure

🔧 MCP Server Integration

Available MCP Tools

1. installer_get_settings

2. installer_complete_config

3. installer_validate_config

4. installer_get_defaults

5. installer_platform_recommendations

6. installer_service_recommendations

7. installer_resource_recommendations

🔄 Integration Workflows

Workflow 1: Interactive Installation with MCP Recommendations

Workflow 2: Unattended Installation with Config File

Workflow 3: Taskserv Self-Installation

📦 Nushell Deployment Scripts

Location

Usage

1. Interactive Deployment

2. Headless Deployment

3. Unattended Deployment

4. Platform-Specific Deployment

5. MCP Integration

🧪 Testing

Test Interactive Installation

Test Headless Installation

Test Unattended Installation

Test MCP Tools

Test Nushell Scripts

🔍 Troubleshooting

Issue: Config file not found

Issue: Platform not detected

Issue: Resource requirements not met

Issue: MCP server not responding

Issue: Webhook notifications failing

📚 Configuration Reference

Complete Example (Enterprise)

🎯 Best Practices

1. Configuration Management

2. Security

3. Deployment

4. Scaling

📖 Additional Resources

Documentation

Examples

Support

✅ Completion Checklist

18 KiB

Raw Blame History