provisioning/scripts/setup-platform-config.sh.md

# Platform Services Configuration Setup Script

**Path**: `provisioning/scripts/setup-platform-config.sh`

Setup and manage platform service configurations in `provisioning/config/runtime/`.

## Features

- ✅ **Interactive Mode**: Guided setup with TypeDialog or quick mode
- ✅ **Interactive TypeDialog**: Web/TUI/CLI form-based configuration
- ✅ **Quick Mode**: Auto-setup from defaults + mode overlays
- ✅ **Automatic TOML Export**: Generates TOML files for Rust services
- ✅ **Runtime Detection**: Detect existing configs and offer update/replace options
- ✅ **Batch Operations**: Configure all 8 services at once
- ✅ **Cleanup Management**: Remove/reset configurations safely

## Usage

### Interactive Setup (Recommended)

```bash
# Start interactive wizard
./provisioning/scripts/setup-platform-config.sh

# Prompts for:
# 1. Action: TypeDialog, Quick Mode, Clean, or List
# 2. Service (if TypeDialog/Quick)
# 3. Mode (solo/multiuser/cicd/enterprise)
# 4. Backend (web/tui/cli, if TypeDialog)
```bash

### Command-Line Options

```bash
# Configure specific service via TypeDialog
./provisioning/scripts/setup-platform-config.sh \
  --service orchestrator \
  --mode solo \
  --backend web

# Quick setup all services for enterprise mode
./provisioning/scripts/setup-platform-config.sh \
  --quick-mode \
  --mode enterprise

# Regenerate TOML files from existing .ncl configs
./provisioning/scripts/setup-platform-config.sh \
  --generate-toml

# List available options
./provisioning/scripts/setup-platform-config.sh --list-modes
./provisioning/scripts/setup-platform-config.sh --list-services
./provisioning/scripts/setup-platform-config.sh --list-configs

# Clean all runtime configurations
./provisioning/scripts/setup-platform-config.sh --clean
```bash

## Workflow

### 1. Initial Setup (Empty Runtime)

```bash
Interactive Prompt
  ↓
├─ TypeDialog (Recommended)
│  ├─ Load form definitions
│  ├─ User fills form (web/tui/cli)
│  └─ Generates orchestrator.solo.ncl
│     ↓
│     Auto-export to orchestrator.solo.toml
│
└─ Quick Mode
   ├─ Select mode (solo/multiuser/cicd/enterprise)
   ├─ Compose all services: defaults + mode overlay
   ├─ Create 8 .ncl files
   └─ Auto-export to 8 .toml files
```bash

### 2. Update Existing Configuration

```bash
Detect Existing Config
  ↓
Choose Action:
  ├─ Clean up & start fresh
  ├─ Update via TypeDialog (edit existing)
  ├─ Use quick mode (regenerate)
  └─ List current configs
```bash

### 3. Manual NCL Edits

```bash
User edits: provisioning/config/runtime/orchestrator.solo.ncl
  ↓
Run: ./setup-platform-config.sh --generate-toml
  ↓
Auto-exports to: provisioning/config/runtime/generated/orchestrator.solo.toml
  ↓
Service loads TOML automatically
```bash

## Configuration Layers

The script composes configurations from multiple layers:

```bash
1. Schema (TYPE-SAFE CONTRACT)
   ↓
   provisioning/schemas/platform/schemas/orchestrator.ncl
   (Defines valid fields, types, constraints)

2. Service Defaults (BASE VALUES)
   ↓
   provisioning/schemas/platform/defaults/orchestrator-defaults.ncl
   (Default values for all orchestrator settings)

3. Mode Overlay (MODE-SPECIFIC TUNING)
   ↓
   provisioning/schemas/platform/defaults/deployment/solo-defaults.ncl
   (Resource limits for solo mode: 2 CPU, 4GB RAM)

4. Composition (MERGE)
   ↓
   defaults.merge_config_with_mode(mode_config)
   (Merges base + mode overlay)

5. Runtime Config (USER CUSTOMIZATION)
   ↓
   provisioning/config/runtime/orchestrator.solo.ncl
   (Final config, can be hand-edited)

6. TOML Export (SERVICE CONSUMPTION)
   ↓
   provisioning/config/runtime/generated/orchestrator.solo.toml
   (Rust service reads this)
```bash

## Services & Modes

### 8 Available Services

```bash
1. orchestrator         - Main orchestration engine
2. control-center       - Web UI and management console
3. mcp-server           - Model Context Protocol server
4. vault-service        - Secrets management and encryption
5. extension-registry   - Extension distribution system
6. rag                  - Retrieval-Augmented Generation
7. ai-service           - AI model integration
8. provisioning-daemon  - Background operations
```bash

### 4 Deployment Modes

| Mode | Specs | Use Case |
| ------ | ------- | ---------- |
| `solo` | 2 CPU, 4GB RAM | Development, testing |
| `multiuser` | 4 CPU, 8GB RAM | Team staging |
| `cicd` | 8 CPU, 16GB RAM | CI/CD pipelines |
| `enterprise` | 16+ CPU, 32+ GB | Production HA |

## Directory Structure

```bash
provisioning/
├── config/
│   └── runtime/                    # 🔒 PRIVATE (gitignored)
│       ├── .gitignore
│       ├── orchestrator.solo.ncl         # Runtime config (user editable)
│       ├── vault-service.multiuser.ncl   # Runtime config
│       └── generated/                    # TOMLs (auto-generated)
│           ├── orchestrator.solo.toml         # For Rust services
│           └── vault-service.multiuser.toml
│
├── schemas/platform/               # 📘 PUBLIC (versionable)
│   ├── schemas/                    # Type contracts
│   ├── defaults/                   # Base values
│   │   ├── orchestrator-defaults.ncl
│   │   └── deployment/
│   │       ├── solo-defaults.ncl
│   │       ├── multiuser-defaults.ncl
│   │       ├── cicd-defaults.ncl
│   │       └── enterprise-defaults.ncl
│   └── validators/                 # Business logic
│
└── scripts/
    └── setup-platform-config.sh    # This script
```bash

## Requirements

- **Bash 4.0+**
- **Nickel 0.10+** - Configuration language
- **Nushell 0.109+** - Script engine
- **TypeDialog** (optional, for interactive setup)

## Integration with Provisioning Installer

### ⚠️ Current Status: Installer NOT YET IMPLEMENTED

The `setup-platform-config.sh` script is a **standalone tool** ready to use independently.

**For now**: Call the script manually before running services

```bash
# Step 1: Setup platform configurations (MANUAL)
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo

# Step 2: Run services
export ORCHESTRATOR_MODE=solo
cargo run -p orchestrator
```bash

### Future: When Installer is Implemented

Once `provisioning/scripts/install.sh` is ready, it will look like:

```bash
#!/bin/bash
# provisioning/scripts/install.sh (FUTURE)

# Pre-flight checks
check_dependencies() {
    command -v nickel >/dev/null || { echo "Nickel required"; exit 1; }
    command -v nu >/dev/null || { echo "Nushell required"; exit 1; }
}
check_dependencies

# Install provisioning system
echo "Installing provisioning system..."
# (implementation here)

# Setup platform configurations
echo "Setting up platform configurations..."
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo

# Build and verify
echo "Building platform services..."
cargo build -p orchestrator -p control-center -p mcp-server

echo "Installation complete!"
```bash

### CI/CD Integration (Available Now)

For CI/CD pipelines that don't require the full installer:

```bash
#!/bin/bash
# ci/setup.sh

# Setup configurations for CI/CD mode
./provisioning/scripts/setup-platform-config.sh \
  --quick-mode \
  --mode cicd

# Run tests
cargo test --all

# Deploy
docker-compose -f provisioning/platform/infrastructure/docker/docker-compose.cicd.yml up
```bash

## Important Notes

### ⚠️ Manual Edits

If you manually edit `.ncl` files in `provisioning/config/runtime/`:

```bash
# Always regenerate TOMLs afterward
./provisioning/scripts/setup-platform-config.sh --generate-toml
```bash

### 🔒 Private Configurations

Files in `provisioning/config/runtime/` are **gitignored**:
- `.ncl` files (may contain secrets/encrypted values)
- `generated/*.toml` files (auto-generated, no need to version)

### 📘 Public Schemas

Schemas in `provisioning/schemas/platform/` are **public**:
- Source of truth for configuration structure
- Versionable and shared across team
- Can be committed to git

### 🔄 Regeneration

The script is **idempotent** - run it multiple times safely:

```bash
# Safe: Re-runs setup, updates configs
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode multiuser

# Does NOT overwrite manually edited files (unless --clean is used)
```bash

## Troubleshooting

### Nickel Validation Fails

```bash
# Check syntax of generated config
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# View detailed error
nickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl
```bash

### TOML Export Fails

```bash
# Check if Nickel config is valid
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# Try manual export
nickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl
```bash

### Service Won't Start

```bash
# Verify TOML exists
ls -la provisioning/config/runtime/generated/orchestrator.solo.toml

# Check TOML syntax
cat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20

# Verify service can read TOML
ORCHESTRATOR_MODE=solo cargo run -p orchestrator --
```bash

## Examples

### Example 1: Quick Setup for Development

```bash
# Setup all services for solo mode (2 CPU, 4GB RAM)
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo

# Result:
# ✓ Created provisioning/config/runtime/orchestrator.solo.ncl
# ✓ Created provisioning/config/runtime/control-center.solo.ncl
# ✓ ... (8 services total)
# ✓ Generated 8 TOML files in provisioning/config/runtime/generated/

# Run service:
export ORCHESTRATOR_MODE=solo
cargo run -p orchestrator
```bash

### Example 2: Interactive TypeDialog Setup

```bash
# Configure orchestrator in multiuser mode with web UI
./provisioning/scripts/setup-platform-config.sh \
  --service orchestrator \
  --mode multiuser \
  --backend web

# TypeDialog opens browser, user fills form
# Result:
# ✓ Created provisioning/config/runtime/orchestrator.multiuser.ncl
# ✓ Generated provisioning/config/runtime/generated/orchestrator.multiuser.toml

# Run service:
export ORCHESTRATOR_MODE=multiuser
cargo run -p orchestrator
```bash

### Example 3: Update After Manual Edit

```bash
# Edit config manually
vim provisioning/config/runtime/orchestrator.solo.ncl

# Regenerate TOML (critical!)
./provisioning/scripts/setup-platform-config.sh --generate-toml

# Verify changes
cat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20

# Restart service with new config
pkill orchestrator
ORCHESTRATOR_MODE=solo cargo run -p orchestrator
```bash

## Performance Notes

- **Quick Mode**: ~1-2 seconds (no user interaction, direct composition)
- **TypeDialog (web)**: 10-30 seconds (server startup + UI loading)
- **TOML Export**: <1 second per service
- **Full Setup**: 5-10 minutes (8 services via TypeDialog)

---

**Version**: 1.0.0
**Created**: 2026-01-05
**Last Updated**: 2026-01-05