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