provisioning/docs/src/getting-started/05-platform-configuration.md

Platform Service Configuration

After verifying your installation, the next step is to configure the platform services. This guide walks you through setting up your provisioning platform for deployment.

What You'll Learn

• Understanding platform services and configuration modes
• Setting up platform configurations with setup-platform-config.sh
• Choosing the right deployment mode for your use case
• Configuring services interactively or with quick mode
• Running platform services with your configuration

Prerequisites

Before configuring platform services, ensure you have:

• ✅ Completed Installation Steps
• ✅ Verified installation with Verification
• ✅ Nickel 0.10+ (for configuration language)
• ✅ Nushell 0.109+ (for scripts)
• ✅ TypeDialog (optional, for interactive configuration)

Platform Services Overview

The provisioning platform consists of 8 core services:

Service	Purpose	Default Mode
orchestrator	Main orchestration engine	Required
control-center	Web UI and management console	Required
mcp-server	Model Context Protocol integration	Optional
vault-service	Secrets management and encryption	Required
extension-registry	Extension distribution system	Required
rag	Retrieval-Augmented Generation	Optional
ai-service	AI model integration	Optional
provisioning-daemon	Background operations	Required

Deployment Modes

Choose a deployment mode based on your needs:

Mode	Resources	Use Case
solo	2 CPU, 4 GB RAM	Development, testing, local machines
multiuser	4 CPU, 8 GB RAM	Team staging, team development
cicd	8 CPU, 16 GB RAM	CI/CD pipelines, automated testing
enterprise	16+ CPU, 32+ GB	Production, high-availability

Step 1: Initialize Configuration Script

The configuration system is managed by a standalone script that doesn't require the main installer:

# Navigate to the provisioning directory
cd /path/to/project-provisioning

# Verify the setup script exists
ls -la provisioning/scripts/setup-platform-config.sh

# Make script executable
chmod +x provisioning/scripts/setup-platform-config.sh

Step 2: Choose Configuration Method

Method A: Interactive TypeDialog Configuration (Recommended)

TypeDialog provides an interactive form-based configuration interface available in multiple backends (web, TUI, CLI).

Quick Interactive Setup (All Services at Once)

# Run interactive setup - prompts for choices
./provisioning/scripts/setup-platform-config.sh

# Follow the prompts to:
# 1. Choose action (TypeDialog, Quick Mode, Clean, List)
# 2. Select service (or all services)
# 3. Choose deployment mode
# 4. Select backend (web, tui, cli)

Configure Specific Service with TypeDialog

# Configure orchestrator in solo mode with web UI
./provisioning/scripts/setup-platform-config.sh \
  --service orchestrator \
  --mode solo \
  --backend web

# TypeDialog opens browser → User fills form → Config generated

When to use TypeDialog:

• First-time setup with visual form guidance
• Updating configuration with validation
• Multiple services needing coordinated changes
• Team environments where UI is preferred

Method B: Quick Mode Configuration (Fastest)

Quick mode automatically creates all service configurations from defaults overlaid with mode-specific tuning.

# Quick setup for solo development mode
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo

# Quick setup for enterprise production
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode enterprise

# Result: All 8 services configured immediately with appropriate resource limits

When to use Quick Mode:

• Initial setup with standard defaults
• Switching deployment modes
• CI/CD automated setup
• Scripted/programmatic configuration

Method C: Manual Nickel Configuration

For advanced users who prefer editing configuration files directly:

# View schema definition
cat provisioning/schemas/platform/schemas/orchestrator.ncl

# View default values
cat provisioning/schemas/platform/defaults/orchestrator-defaults.ncl

# View mode overlay
cat provisioning/schemas/platform/defaults/deployment/solo-defaults.ncl

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

# Validate Nickel syntax
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# Regenerate TOML from edited config (CRITICAL STEP)
./provisioning/scripts/setup-platform-config.sh --generate-toml

When to use Manual Edit:

• Advanced customization beyond form options
• Programmatic configuration generation
• Integration with CI/CD systems
• Custom workspace-specific overrides

Step 3: Understand Configuration Layers

The configuration system uses layered composition:

1. Schema (Type contract)
   ↓ Defines valid fields and constraints

2. Service Defaults (Base values)
   ↓ Default configuration for each service

3. Mode Overlay (Mode-specific tuning)
   ↓ solo, multiuser, cicd, or enterprise settings

4. User Customization (Overrides)
   ↓ User-specific or workspace-specific changes

5. Runtime Config (Final result)
   ↓ provisioning/config/runtime/orchestrator.solo.ncl

6. TOML Export (Service consumption)
   ↓ provisioning/config/runtime/generated/orchestrator.solo.toml

All layers are automatically composed and validated.

Step 4: Verify Generated Configuration

After running the setup script, verify the configuration was created:

# List generated runtime configurations
ls -la provisioning/config/runtime/

# Check generated TOML files
ls -la provisioning/config/runtime/generated/

# Verify TOML is valid
cat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20

You should see files for all 8 services in both the runtime directory (Nickel format) and the generated directory (TOML format).

Step 5: Run Platform Services

After successful configuration, services can be started:

Running a Single Service

# Set deployment mode
export ORCHESTRATOR_MODE=solo

# Run the orchestrator service
cd provisioning/platform
cargo run -p orchestrator

Running Multiple Services

# Terminal 1: Vault Service (secrets management)
export VAULT_MODE=solo
cargo run -p vault-service

# Terminal 2: Orchestrator (main service)
export ORCHESTRATOR_MODE=solo
cargo run -p orchestrator

# Terminal 3: Control Center (web UI)
export CONTROL_CENTER_MODE=solo
cargo run -p control-center

# Access web UI at http://localhost:8080 (default)

Docker-Based Deployment

# Start all services in Docker (requires docker-compose.yml)
cd provisioning/platform/infrastructure/docker
docker-compose -f docker-compose.solo.yml up

# Or for enterprise mode
docker-compose -f docker-compose.enterprise.yml up

Step 6: Verify Services Are Running

# Check orchestrator status
curl http://localhost:9000/health

# Check control center web UI
open http://localhost:8080

# View service logs
export ORCHESTRATOR_MODE=solo
cargo run -p orchestrator -- --log-level debug

Customizing Configuration

Scenario: Change Deployment Mode

If you need to switch from solo to multiuser mode:

# Option 1: Re-run setup with new mode
./provisioning/scripts/setup-platform-config.sh --quick-mode --mode multiuser

# Option 2: Interactive update via TypeDialog
./provisioning/scripts/setup-platform-config.sh --service orchestrator --mode multiuser --backend web

# Result: All configurations updated for multiuser mode
#         Services read from provisioning/config/runtime/generated/orchestrator.multiuser.toml

Scenario: Manual Configuration Edit

If you need fine-grained control:

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

# 2. Make your changes (for example, change port, add environment variables)

# 3. Validate syntax
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# 4. CRITICAL: Regenerate TOML (services won't see changes without this)
./provisioning/scripts/setup-platform-config.sh --generate-toml

# 5. Verify TOML was updated
stat provisioning/config/runtime/generated/orchestrator.solo.toml

# 6. Restart service with new configuration
pkill orchestrator
export ORCHESTRATOR_MODE=solo
cargo run -p orchestrator

Scenario: Workspace-Specific Overrides

For workspace-specific customization:

# Create workspace override file
mkdir -p workspace_myworkspace/config
cat > workspace_myworkspace/config/platform-overrides.ncl <<'EOF'
# Workspace-specific settings
{
  orchestrator = {
    server.port = 9999,  # Custom port
    workspace.name = "myworkspace"
  },

  control_center = {
    workspace.name = "myworkspace"
  }
}
EOF

# Generate config with workspace overrides
./provisioning/scripts/setup-platform-config.sh --workspace workspace_myworkspace

# Configuration system merges: defaults + mode overlay + workspace overrides

Available Configuration Commands

# List all available modes
./provisioning/scripts/setup-platform-config.sh --list-modes
# Output: solo, multiuser, cicd, enterprise

# List all configurable services
./provisioning/scripts/setup-platform-config.sh --list-services
# Output: orchestrator, control-center, mcp-server, vault-service, extension-registry, rag, ai-service, provisioning-daemon

# List current configurations
./provisioning/scripts/setup-platform-config.sh --list-configs
# Output: Shows current runtime configurations and their status

# Clean all runtime configurations (use with caution)
./provisioning/scripts/setup-platform-config.sh --clean
# Removes: provisioning/config/runtime/*.ncl
#          provisioning/config/runtime/generated/*.toml

Configuration File Locations

Public Definitions (Part of repository)

provisioning/schemas/platform/
├── schemas/              # Type contracts (Nickel)
├── defaults/             # Base configuration values
│   └── deployment/       # Mode-specific: solo, multiuser, cicd, enterprise
├── validators/           # Business logic validation
├── templates/            # Configuration generation templates
└── constraints/          # Validation limits

Private Runtime Configs (Gitignored)

provisioning/config/runtime/              # User-specific deployments
├── orchestrator.solo.ncl                 # Editable config
├── orchestrator.multiuser.ncl
└── generated/                            # Auto-generated, don't edit
    ├── orchestrator.solo.toml            # For Rust services
    └── orchestrator.multiuser.toml

Examples (Reference)

provisioning/config/examples/
├── orchestrator.solo.example.ncl         # Solo mode reference
└── orchestrator.enterprise.example.ncl   # Enterprise mode reference

Troubleshooting Configuration

Issue: Script Fails with "Nickel not found"

# Install Nickel
# macOS
brew install nickel

# Linux
cargo install nickel --version 0.10

# Verify installation
nickel --version
# Expected: 0.10.0 or higher

Issue: Configuration Won't Generate TOML

# Check Nickel syntax
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# If errors found, view detailed message
nickel typecheck -i provisioning/config/runtime/orchestrator.solo.ncl

# Try manual export
nickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl

Issue: Service Can't Read Configuration

# Verify TOML file exists
ls -la provisioning/config/runtime/generated/orchestrator.solo.toml

# Verify file is valid TOML
head -20 provisioning/config/runtime/generated/orchestrator.solo.toml

# Check service is looking in right location
echo $ORCHESTRATOR_MODE  # Should be set to 'solo', 'multiuser', etc.

# Verify environment variable is correct
export ORCHESTRATOR_MODE=solo
cargo run -p orchestrator --verbose

Issue: Services Won't Start After Config Change

# If you edited .ncl file manually, TOML must be regenerated
./provisioning/scripts/setup-platform-config.sh --generate-toml

# Verify new TOML was created
stat provisioning/config/runtime/generated/orchestrator.solo.toml

# Check modification time (should be recent)
ls -lah provisioning/config/runtime/generated/orchestrator.solo.toml

Important Notes

🔒 Runtime Configurations Are Private

Files in provisioning/config/runtime/ are gitignored because:

• May contain encrypted secrets or credentials
• Deployment-specific (different per environment)
• User-customized (each developer/machine has different needs)

📘 Schemas Are Public

Files in provisioning/schemas/platform/ are version-controlled because:

• Define product structure and constraints
• Part of official releases
• Source of truth for configuration format
• Shared across the team

🔄 Configuration Is Idempotent

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 without --clean
./provisioning/scripts/setup-platform-config.sh --generate-toml

# Only deletes on explicit request
./provisioning/scripts/setup-platform-config.sh --clean

⚠️ Installer Status

The full provisioning installer (provisioning/scripts/install.sh) is not yet implemented. Currently:

• ✅ Configuration setup script is standalone and ready to use
• ⏳ Full installer integration is planned for future release
• ✅ Manual workflow works perfectly without installer
• ✅ CI/CD integration available now

Next Steps

After completing platform configuration:

1. Run Services: Start your platform services with configured settings
2. Access Web UI: Open Control Center at http://localhost:8080 (default)
3. Create First Infrastructure: Deploy your first servers and clusters
4. Set Up Extensions: Configure providers and task services for your needs
5. Backup Configuration: Back up runtime configs to private repository

Additional Resources

• Setup Status & Current System Status - Quick reference for system readiness
• Configuration README - Detailed configuration management guide
• Setup Script Documentation - Complete script reference
• TypeDialog Platform Config Guide - Advanced configuration topics
• Deployment Guide - Production deployment procedures

---

Version: 1.0.0 Last Updated: 2026-01-05 Difficulty: Beginner to Intermediate