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](02-installation.md)
- ✅ Verified installation with [Verification](04-verification.md)
- ✅ **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:

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

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

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

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

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

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

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

```bash
# Set deployment mode
export ORCHESTRATOR_MODE=solo

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

### Running Multiple Services

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
# 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](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](../../provisioning/config/SETUP_STATUS.md) - Quick reference for system readiness
- [Configuration README](../../provisioning/config/README.md) - Detailed configuration management guide
- [Setup Script Documentation](../../provisioning/scripts/setup-platform-config.sh.md) - Complete script reference
- [TypeDialog Platform Config Guide](../development/typedialog-platform-config-guide.md) - Advanced configuration topics
- [Deployment Guide](../operations/deployment-guide.md) - Production deployment procedures

---

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