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)

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

Command-Line Options

# 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

Workflow

1. Initial Setup (Empty Runtime)

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

2. Update Existing Configuration

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

3. Manual NCL Edits

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

Configuration Layers

The script composes configurations from multiple layers:

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)

Services & Modes

8 Available Services

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

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

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

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

# 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

Future: When Installer is Implemented

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

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

CI/CD Integration (Available Now)

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

#!/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

Important Notes

⚠️ Manual Edits

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

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

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

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

Troubleshooting

Nickel Validation Fails

# 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

TOML Export Fails

# 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

Service Won't Start

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

Examples

Example 1: Quick Setup for Development

# 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

Example 2: Interactive TypeDialog Setup

# 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

Example 3: Update After Manual Edit

# 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

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