provisioning/config/README.md

Platform Configuration Management

This directory manages runtime configurations for provisioning platform services.

Structure

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)

# 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

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

# Update via TypeDialog UI
./provisioning/scripts/setup-platform-config.sh --service orchestrator --mode solo

Option B: Manual Edit

# Edit Nickel directly
vim provisioning/config/runtime/orchestrator.solo.ncl

# ⚠️ CRITICAL: Regenerate TOML afterward
./provisioning/scripts/setup-platform-config.sh --generate-toml

Configuration Layers

📘 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

# 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

# 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

# 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

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:

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

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

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:

# 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

# 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

# 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

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

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

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

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