403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# 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
|