prvng_platform/installer/docs/CONFIGURATION_INTEGRATION_GUIDE.md

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

```bash
# 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)

```bash
# 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)

```bash
# 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

1. **Template** (copy and customize):
   ```
   provisioning/config/installer-config.toml.template
   ```

2. **Examples** (ready to use):
   ```
   provisioning/config/installer-examples/
   ├── solo.toml
   ├── multi-user.toml
   ├── cicd.toml
   └── enterprise.toml
   ```

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

### Configuration Structure

```toml
[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**:
```json
{
  "query": "solo developer setup for docker"
}
```

**Output**:
```json
{
  "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**:
```json
{
  "config": {
    "deployment": {
      "mode": "cicd"
    }
  }
}
```

**Output**:
```json
{
  "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**:
```json
{
  "config": {
    "deployment": {
      "platform": "docker",
      "mode": "enterprise"
    },
    "resources": {
      "min_cpu_cores": 2  // Too low for enterprise
    }
  }
}
```

**Output**:
```json
{
  "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**:
```json
{
  "mode": "multi-user"
}
```

**Output**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "mode": "cicd"
}
```

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

#### 7. installer_resource_recommendations

Resource optimization.

**Input**:
```json
{
  "mode": "solo"
}
```

**Output**:
```json
{
  "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

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

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

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

```nushell
use deploy.nu *

# Launch Rust TUI installer
deploy-interactive
```

#### 2. Headless Deployment

```nushell
use deploy.nu *

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

#### 3. Unattended Deployment

```nushell
use deploy.nu *

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

#### 4. Platform-Specific Deployment

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

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

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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**:
```bash
# 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**:
```bash
# 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**:
1. Choose lower mode (e.g., solo instead of multi-user)
2. Override resource checks in config:
   ```toml
   [resources]
   min_cpu_cores = 2  # Lower requirement
   ```
3. Disable services to reduce load

### Issue: MCP server not responding

**Error**: `Failed to query MCP server`

**Solution**:
```bash
# 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**:
1. Check webhook URL is correct
2. Verify network connectivity:
   ```bash
   curl -X POST https://hooks.slack.com/... -d '{"text":"test"}'
   ```
3. Check webhook configuration in config.toml:
   ```toml
   [unattended.notification]
   webhook_url = "https://..."
   retry_attempts = 3
   ```

---

## 📚 Configuration Reference

### Complete Example (Enterprise)

```toml
[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. 🎉