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)

```bash
# 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)**
```bash
# 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

```
📘 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

```bash
# 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

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

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

```
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

```bash
# 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

```bash
# 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`