392 lines
11 KiB
Markdown
392 lines
11 KiB
Markdown
# Platform Configuration Management
|
|
|
|
This directory manages **runtime configurations** for provisioning platform services.
|
|
|
|
## Structure
|
|
|
|
```bash
|
|
provisioning/config/
|
|
├── runtime/ # 🔒 PRIVATE (gitignored)
|
|
│ ├── .gitignore # Runtime files are private
|
|
│ ├── orchestrator.solo.ncl # Runtime config (editable)
|
|
│ ├── vault-service.multiuser.ncl # Runtime config (editable)
|
|
│ └── generated/ # 📄 Auto-generated TOMLs
|
|
│ ├── orchestrator.solo.toml # Exported from .ncl
|
|
│ └── vault-service.multiuser.toml
|
|
│
|
|
├── examples/ # 📘 PUBLIC (reference)
|
|
│ ├── orchestrator.solo.example.ncl
|
|
│ └── orchestrator.enterprise.example.ncl
|
|
│
|
|
├── README.md # This file
|
|
└── setup-platform-config.sh # ← See provisioning/scripts/setup-platform-config.sh
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### 1. Setup Platform Configuration (First Time)
|
|
|
|
```toml
|
|
# Interactive wizard (recommended)
|
|
./provisioning/scripts/setup-platform-config.sh
|
|
|
|
# Or quick setup for all services in solo mode
|
|
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo
|
|
```
|
|
|
|
### 2. Run Services
|
|
|
|
```bash
|
|
# Service reads config from generated TOML
|
|
export ORCHESTRATOR_MODE=solo
|
|
cargo run -p orchestrator
|
|
|
|
# Or with explicit config path
|
|
export ORCHESTRATOR_CONFIG=provisioning/config/runtime/generated/orchestrator.solo.toml
|
|
cargo run -p orchestrator
|
|
```
|
|
|
|
### 3. Update Configuration
|
|
|
|
**Option A: Interactive (Recommended)**
|
|
```toml
|
|
# Update via TypeDialog UI
|
|
./provisioning/scripts/setup-platform-config.sh --service orchestrator --mode solo
|
|
```
|
|
|
|
**Option B: Manual Edit**
|
|
```bash
|
|
# Edit Nickel directly
|
|
vim provisioning/config/runtime/orchestrator.solo.ncl
|
|
|
|
# ⚠️ CRITICAL: Regenerate TOML afterward
|
|
./provisioning/scripts/setup-platform-config.sh --generate-toml
|
|
```
|
|
|
|
## Configuration Layers
|
|
|
|
```toml
|
|
📘 PUBLIC (provisioning/schemas/platform/)
|
|
├── schemas/ → Type contracts (Nickel)
|
|
├── defaults/ → Base configuration values
|
|
│ └── deployment/ → Mode-specific overlays (solo/multiuser/cicd/enterprise)
|
|
├── validators/ → Business logic validation
|
|
└── common/
|
|
└── helpers.ncl → Merge functions
|
|
|
|
⬇️ COMPOSITION PROCESS ⬇️
|
|
|
|
🔒 PRIVATE (provisioning/config/runtime/)
|
|
├── orchestrator.solo.ncl ← User editable
|
|
│ (imports schemas + defaults + mode overlay)
|
|
│ (uses helpers.compose_config for merge)
|
|
│
|
|
└── generated/
|
|
└── orchestrator.solo.toml ← Auto-exported for Rust services
|
|
(generated by: nickel export --format toml)
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
### Schema (Type Contract)
|
|
- **File**: `provisioning/schemas/platform/schemas/orchestrator.ncl`
|
|
- **Purpose**: Defines valid fields, types, constraints
|
|
- **Status**: 📘 PUBLIC, versioned, source of truth
|
|
- **Edit**: Rarely (architecture changes only)
|
|
|
|
### Defaults (Base Values)
|
|
- **File**: `provisioning/schemas/platform/defaults/orchestrator-defaults.ncl`
|
|
- **Purpose**: Default values for all orchestrator settings
|
|
- **Status**: 📘 PUBLIC, versioned, part of product
|
|
- **Edit**: When changing default behavior
|
|
|
|
### Mode Overlay (Tuning)
|
|
- **File**: `provisioning/schemas/platform/defaults/deployment/solo-defaults.ncl`
|
|
- **Purpose**: Mode-specific resource/behavior tuning
|
|
- **Status**: 📘 PUBLIC, versioned
|
|
- **Example**: solo mode uses 2 CPU, enterprise uses 16+ CPU
|
|
|
|
### Runtime Config (User Customization)
|
|
- **File**: `provisioning/config/runtime/orchestrator.solo.ncl`
|
|
- **Purpose**: Actual deployment configuration (can be hand-edited)
|
|
- **Status**: 🔒 PRIVATE, gitignored
|
|
- **Edit**: Yes, use setup script or edit manually + regenerate TOML
|
|
|
|
### Generated TOML (Service Consumption)
|
|
- **File**: `provisioning/config/runtime/generated/orchestrator.solo.toml`
|
|
- **Purpose**: What Rust services actually read
|
|
- **Status**: 🔒 PRIVATE, gitignored, auto-generated
|
|
- **Edit**: NO - regenerate from .ncl instead
|
|
- **Generation**: `nickel export --format toml <ncl_file>`
|
|
|
|
## Workflows
|
|
|
|
### Scenario 1: First-Time Setup
|
|
|
|
```bash
|
|
# 1. Run setup script
|
|
./provisioning/scripts/setup-platform-config.sh
|
|
|
|
# 2. Choose action (TypeDialog or Quick Mode)
|
|
# ↓
|
|
# TypeDialog: User fills form → generates orchestrator.solo.ncl
|
|
# Quick Mode: Composes defaults + mode overlay → generates all 8 services
|
|
|
|
# 3. Script auto-exports to TOML
|
|
# orchestrator.solo.ncl → orchestrator.solo.toml
|
|
|
|
# 4. Service reads TOML
|
|
# cargo run -p orchestrator (reads generated/orchestrator.solo.toml)
|
|
```
|
|
|
|
### Scenario 2: Update Configuration
|
|
|
|
```toml
|
|
# Option A: Interactive TypeDialog
|
|
./provisioning/scripts/setup-platform-config.sh
|
|
--service orchestrator
|
|
--mode solo
|
|
--backend web
|
|
|
|
# Result: Updated orchestrator.solo.ncl + auto-exported TOML
|
|
|
|
# Option B: Manual Edit
|
|
vim provisioning/config/runtime/orchestrator.solo.ncl
|
|
|
|
# ⚠️ CRITICAL: Must regenerate TOML
|
|
./provisioning/scripts/setup-platform-config.sh --generate-toml
|
|
|
|
# Result: Updated TOML in generated/
|
|
```
|
|
|
|
### Scenario 3: Switch Deployment Mode
|
|
|
|
```bash
|
|
# From solo to enterprise
|
|
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode enterprise
|
|
|
|
# Result: All 8 services configured for enterprise mode
|
|
# 16+ CPU, 32+ GB RAM, HA setup, KMS integration, etc.
|
|
```
|
|
|
|
### Scenario 4: Workspace-Specific Overrides
|
|
|
|
```bash
|
|
workspace_librecloud/
|
|
├── config/
|
|
│ └── platform-overrides.ncl # Workspace customization
|
|
│
|
|
# Example:
|
|
# {
|
|
# orchestrator.server.port = 9999,
|
|
# orchestrator.workspace.name = "librecloud",
|
|
# vault-service.storage.path = "./workspace_librecloud/data/vault"
|
|
# }
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
### ⚠️ Manual Edits Require TOML Regeneration
|
|
|
|
If you edit `.ncl` files directly:
|
|
|
|
```nickel
|
|
# 1. Edit the .ncl file
|
|
vim provisioning/config/runtime/orchestrator.solo.ncl
|
|
|
|
# 2. ALWAYS regenerate TOML
|
|
./provisioning/scripts/setup-platform-config.sh --generate-toml
|
|
|
|
# Service will NOT see your changes until TOML is regenerated
|
|
```
|
|
|
|
### 🔒 Private by Design
|
|
|
|
Runtime configs are **gitignored** for good reasons:
|
|
|
|
- **May contain secrets**: Encrypted credentials, API keys, tokens
|
|
- **Deployment-specific**: Different values per environment
|
|
- **User-customized**: Each developer/workspace has different needs
|
|
- **Not shared**: Don't commit locally-built configs
|
|
|
|
### 📘 Schemas are Public
|
|
|
|
Schema/defaults in `provisioning/schemas/` are **version-controlled**:
|
|
|
|
- Product definition (part of releases)
|
|
- Shared across team
|
|
- Source of truth for config structure
|
|
- Can reference in documentation
|
|
|
|
### 🔄 Idempotent Setup
|
|
|
|
The setup script is safe to run multiple times:
|
|
|
|
```bash
|
|
# Safe: Updates only what's needed
|
|
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode enterprise
|
|
|
|
# Safe: Doesn't overwrite unless --clean is used
|
|
./provisioning/scripts/setup-platform-config.sh --generate-toml
|
|
|
|
# Use --clean to start fresh
|
|
./provisioning/scripts/setup-platform-config.sh --clean
|
|
```
|
|
|
|
## Service Configuration Paths
|
|
|
|
Each service loads config using this priority:
|
|
|
|
```toml
|
|
1. Environment variable: ORCHESTRATOR_CONFIG=/path/to/custom.toml
|
|
2. Mode-specific runtime: provisioning/config/runtime/generated/orchestrator.{MODE}.toml
|
|
3. Fallback defaults: provisioning/schemas/platform/defaults/orchestrator-defaults.ncl
|
|
```
|
|
|
|
## Configuration Composition (Technical)
|
|
|
|
The setup script uses Nickel's `helpers.compose_config` function:
|
|
|
|
```nickel
|
|
# Generated .ncl file imports:
|
|
let helpers = import "provisioning/schemas/platform/common/helpers.ncl"
|
|
let defaults = import "provisioning/schemas/platform/defaults/orchestrator-defaults.ncl"
|
|
let mode_config = import "provisioning/schemas/platform/defaults/deployment/solo-defaults.ncl"
|
|
|
|
# Compose: base + mode overlay
|
|
helpers.compose_config defaults mode_config {}
|
|
# ^base ^mode overlay ^user overrides (empty if not customized)
|
|
```
|
|
|
|
This ensures:
|
|
- Type safety (validated by Nickel schema)
|
|
- Proper layering (base + mode + user)
|
|
- Reproducibility (same compose always produces same result)
|
|
- Extensibility (can add user layer via Nickel import)
|
|
|
|
## Troubleshooting
|
|
|
|
### Config Won't Generate TOML
|
|
|
|
```toml
|
|
# Check Nickel syntax
|
|
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl
|
|
|
|
# Check for schema import errors
|
|
nickel export --format json provisioning/config/runtime/orchestrator.solo.ncl
|
|
|
|
# View detailed error message
|
|
nickel typecheck -i provisioning/config/runtime/orchestrator.solo.ncl 2>&1 | less
|
|
```
|
|
|
|
### Service Won't Start
|
|
|
|
```bash
|
|
# Verify TOML exists
|
|
ls -la provisioning/config/runtime/generated/orchestrator.solo.toml
|
|
|
|
# Verify TOML syntax
|
|
toml-cli validate provisioning/config/runtime/generated/orchestrator.solo.toml
|
|
|
|
# Check service config loading
|
|
RUST_LOG=debug cargo run -p orchestrator 2>&1 | head -50
|
|
```
|
|
|
|
### Wrong Configuration Being Used
|
|
|
|
```toml
|
|
# Verify environment mode
|
|
echo $ORCHESTRATOR_MODE # Should be: solo, multiuser, cicd, or enterprise
|
|
|
|
# Check which file service is reading
|
|
ORCHESTRATOR_CONFIG=provisioning/config/runtime/generated/orchestrator.solo.toml
|
|
cargo run -p orchestrator
|
|
|
|
# Verify file modification time
|
|
ls -lah provisioning/config/runtime/generated/orchestrator.*.toml
|
|
```
|
|
|
|
## Integration Points
|
|
|
|
### ⚠️ Provisioning Installer Status
|
|
|
|
**Current Status**: Installer NOT YET IMPLEMENTED
|
|
|
|
The `setup-platform-config.sh` script is a **standalone tool** that:
|
|
- ✅ Works independently from the provisioning installer
|
|
- ✅ Can be called manually for configuration setup
|
|
- ⏳ Will be integrated into the installer once it's implemented
|
|
|
|
**For Now**: Use script manually before running services:
|
|
|
|
```bash
|
|
# Manual setup (until installer is implemented)
|
|
cd /path/to/project-provisioning
|
|
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo
|
|
|
|
# Then run services
|
|
export ORCHESTRATOR_MODE=solo
|
|
cargo run -p orchestrator
|
|
```
|
|
|
|
### Future: Integration into Provisioning Installer
|
|
|
|
Once `provisioning/scripts/install.sh` is implemented, it will automatically call this script:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# provisioning/scripts/install.sh (FUTURE - NOT YET IMPLEMENTED)
|
|
|
|
# Pre-flight checks (verification of dependencies, paths, permissions)
|
|
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 core provisioning system
|
|
echo "Installing provisioning system..."
|
|
# (install implementation details here)
|
|
|
|
# Setup platform configurations
|
|
echo "Setting up platform configurations..."
|
|
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo
|
|
|
|
# Build and test platform services
|
|
echo "Building platform services..."
|
|
cargo build -p orchestrator -p control-center -p mcp-server
|
|
|
|
# Verify services are operational
|
|
echo "Verification complete - services ready to run"
|
|
```
|
|
|
|
### CI/CD Pipeline Integration
|
|
|
|
For automated CI/CD setups (can use now):
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# ci/setup.sh
|
|
|
|
# Setup configurations for CI/CD mode
|
|
cd /path/to/project-provisioning
|
|
./provisioning/scripts/setup-platform-config.sh
|
|
--quick-mode
|
|
--mode cicd
|
|
|
|
# Result: All services configured for CI/CD mode
|
|
# (ephemeral, API-driven, fast cleanup, minimal resource footprint)
|
|
|
|
# Run tests
|
|
cargo test --all
|
|
|
|
# Deploy (CI/CD specific)
|
|
docker-compose -f provisioning/platform/infrastructure/docker/docker-compose.cicd.yml up
|
|
```
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Last Updated**: 2026-01-05
|
|
**Script Reference**: `provisioning/scripts/setup-platform-config.sh`
|