11 KiB
11 KiB
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)
```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