# Platform Service Configuration\n\nAfter verifying your installation, the next step is to configure the platform services. This guide walks you through setting up your provisioning\nplatform for deployment.\n\n## What You'll Learn\n\n- Understanding platform services and configuration modes\n- Setting up platform configurations with `setup-platform-config.sh`\n- Choosing the right deployment mode for your use case\n- Configuring services interactively or with quick mode\n- Running platform services with your configuration\n\n## Prerequisites\n\nBefore configuring platform services, ensure you have:\n\n- ✅ Completed [Installation Steps](02-installation.md)\n- ✅ Verified installation with [Verification](04-verification.md)\n- ✅ **Nickel** 0.10+ (for configuration language)\n- ✅ **Nushell** 0.109+ (for scripts)\n- ✅ **TypeDialog** (optional, for interactive configuration)\n\n## Platform Services Overview\n\nThe provisioning platform consists of 8 core services:\n\n| Service | Purpose | Default Mode |\n| --------- | --------- | -------------- |\n| **orchestrator** | Main orchestration engine | Required |\n| **control-center** | Web UI and management console | Required |\n| **mcp-server** | Model Context Protocol integration | Optional |\n| **vault-service** | Secrets management and encryption | Required |\n| **extension-registry** | Extension distribution system | Required |\n| **rag** | Retrieval-Augmented Generation | Optional |\n| **ai-service** | AI model integration | Optional |\n| **provisioning-daemon** | Background operations | Required |\n\n## Deployment Modes\n\nChoose a deployment mode based on your needs:\n\n| Mode | Resources | Use Case |\n| ------ | ----------- | ---------- |\n| **solo** | 2 CPU, 4 GB RAM | Development, testing, local machines |\n| **multiuser** | 4 CPU, 8 GB RAM | Team staging, team development |\n| **cicd** | 8 CPU, 16 GB RAM | CI/CD pipelines, automated testing |\n| **enterprise** | 16+ CPU, 32+ GB | Production, high-availability |\n\n## Step 1: Initialize Configuration Script\n\nThe configuration system is managed by a standalone script that doesn't require the main installer:\n\n```\n# Navigate to the provisioning directory\ncd /path/to/project-provisioning\n\n# Verify the setup script exists\nls -la provisioning/scripts/setup-platform-config.sh\n\n# Make script executable\nchmod +x provisioning/scripts/setup-platform-config.sh\n```\n\n## Step 2: Choose Configuration Method\n\n### Method A: Interactive TypeDialog Configuration (Recommended)\n\nTypeDialog provides an interactive form-based configuration interface available in multiple backends (web, TUI, CLI).\n\n#### Quick Interactive Setup (All Services at Once)\n\n```\n# Run interactive setup - prompts for choices\n./provisioning/scripts/setup-platform-config.sh\n\n# Follow the prompts to:\n# 1. Choose action (TypeDialog, Quick Mode, Clean, List)\n# 2. Select service (or all services)\n# 3. Choose deployment mode\n# 4. Select backend (web, tui, cli)\n```\n\n#### Configure Specific Service with TypeDialog\n\n```\n# Configure orchestrator in solo mode with web UI\n./provisioning/scripts/setup-platform-config.sh \\n  --service orchestrator \\n  --mode solo \\n  --backend web\n\n# TypeDialog opens browser → User fills form → Config generated\n```\n\n**When to use TypeDialog:**\n- First-time setup with visual form guidance\n- Updating configuration with validation\n- Multiple services needing coordinated changes\n- Team environments where UI is preferred\n\n### Method B: Quick Mode Configuration (Fastest)\n\nQuick mode automatically creates all service configurations from defaults overlaid with mode-specific tuning.\n\n```\n# Quick setup for solo development mode\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode solo\n\n# Quick setup for enterprise production\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode enterprise\n\n# Result: All 8 services configured immediately with appropriate resource limits\n```\n\n**When to use Quick Mode:**\n- Initial setup with standard defaults\n- Switching deployment modes\n- CI/CD automated setup\n- Scripted/programmatic configuration\n\n### Method C: Manual Nickel Configuration\n\nFor advanced users who prefer editing configuration files directly:\n\n```\n# View schema definition\ncat provisioning/schemas/platform/schemas/orchestrator.ncl\n\n# View default values\ncat provisioning/schemas/platform/defaults/orchestrator-defaults.ncl\n\n# View mode overlay\ncat provisioning/schemas/platform/defaults/deployment/solo-defaults.ncl\n\n# Edit configuration directly\nvim provisioning/config/runtime/orchestrator.solo.ncl\n\n# Validate Nickel syntax\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# Regenerate TOML from edited config (CRITICAL STEP)\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n```\n\n**When to use Manual Edit:**\n- Advanced customization beyond form options\n- Programmatic configuration generation\n- Integration with CI/CD systems\n- Custom workspace-specific overrides\n\n## Step 3: Understand Configuration Layers\n\nThe configuration system uses layered composition:\n\n```\n1. Schema (Type contract)\n   ↓ Defines valid fields and constraints\n\n2. Service Defaults (Base values)\n   ↓ Default configuration for each service\n\n3. Mode Overlay (Mode-specific tuning)\n   ↓ solo, multiuser, cicd, or enterprise settings\n\n4. User Customization (Overrides)\n   ↓ User-specific or workspace-specific changes\n\n5. Runtime Config (Final result)\n   ↓ provisioning/config/runtime/orchestrator.solo.ncl\n\n6. TOML Export (Service consumption)\n   ↓ provisioning/config/runtime/generated/orchestrator.solo.toml\n```\n\nAll layers are automatically composed and validated.\n\n## Step 4: Verify Generated Configuration\n\nAfter running the setup script, verify the configuration was created:\n\n```\n# List generated runtime configurations\nls -la provisioning/config/runtime/\n\n# Check generated TOML files\nls -la provisioning/config/runtime/generated/\n\n# Verify TOML is valid\ncat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20\n```\n\nYou should see files for all 8 services in both the runtime directory (Nickel format) and the generated directory (TOML format).\n\n## Step 5: Run Platform Services\n\nAfter successful configuration, services can be started:\n\n### Running a Single Service\n\n```\n# Set deployment mode\nexport ORCHESTRATOR_MODE=solo\n\n# Run the orchestrator service\ncd provisioning/platform\ncargo run -p orchestrator\n```\n\n### Running Multiple Services\n\n```\n# Terminal 1: Vault Service (secrets management)\nexport VAULT_MODE=solo\ncargo run -p vault-service\n\n# Terminal 2: Orchestrator (main service)\nexport ORCHESTRATOR_MODE=solo\ncargo run -p orchestrator\n\n# Terminal 3: Control Center (web UI)\nexport CONTROL_CENTER_MODE=solo\ncargo run -p control-center\n\n# Access web UI at http://localhost:8080 (default)\n```\n\n### Docker-Based Deployment\n\n```\n# Start all services in Docker (requires docker-compose.yml)\ncd provisioning/platform/infrastructure/docker\ndocker-compose -f docker-compose.solo.yml up\n\n# Or for enterprise mode\ndocker-compose -f docker-compose.enterprise.yml up\n```\n\n## Step 6: Verify Services Are Running\n\n```\n# Check orchestrator status\ncurl http://localhost:9000/health\n\n# Check control center web UI\nopen http://localhost:8080\n\n# View service logs\nexport ORCHESTRATOR_MODE=solo\ncargo run -p orchestrator -- --log-level debug\n```\n\n## Customizing Configuration\n\n### Scenario: Change Deployment Mode\n\nIf you need to switch from solo to multiuser mode:\n\n```\n# Option 1: Re-run setup with new mode\n./provisioning/scripts/setup-platform-config.sh --quick-mode --mode multiuser\n\n# Option 2: Interactive update via TypeDialog\n./provisioning/scripts/setup-platform-config.sh --service orchestrator --mode multiuser --backend web\n\n# Result: All configurations updated for multiuser mode\n#         Services read from provisioning/config/runtime/generated/orchestrator.multiuser.toml\n```\n\n### Scenario: Manual Configuration Edit\n\nIf you need fine-grained control:\n\n```\n# 1. Edit the Nickel configuration directly\nvim provisioning/config/runtime/orchestrator.solo.ncl\n\n# 2. Make your changes (for example, change port, add environment variables)\n\n# 3. Validate syntax\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# 4. CRITICAL: Regenerate TOML (services won't see changes without this)\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n\n# 5. Verify TOML was updated\nstat provisioning/config/runtime/generated/orchestrator.solo.toml\n\n# 6. Restart service with new configuration\npkill orchestrator\nexport ORCHESTRATOR_MODE=solo\ncargo run -p orchestrator\n```\n\n### Scenario: Workspace-Specific Overrides\n\nFor workspace-specific customization:\n\n```\n# Create workspace override file\nmkdir -p workspace_myworkspace/config\ncat > workspace_myworkspace/config/platform-overrides.ncl <<'EOF'\n# Workspace-specific settings\n{\n  orchestrator = {\n    server.port = 9999,  # Custom port\n    workspace.name = "myworkspace"\n  },\n\n  control_center = {\n    workspace.name = "myworkspace"\n  }\n}\nEOF\n\n# Generate config with workspace overrides\n./provisioning/scripts/setup-platform-config.sh --workspace workspace_myworkspace\n\n# Configuration system merges: defaults + mode overlay + workspace overrides\n```\n\n## Available Configuration Commands\n\n```\n# List all available modes\n./provisioning/scripts/setup-platform-config.sh --list-modes\n# Output: solo, multiuser, cicd, enterprise\n\n# List all configurable services\n./provisioning/scripts/setup-platform-config.sh --list-services\n# Output: orchestrator, control-center, mcp-server, vault-service, extension-registry, rag, ai-service, provisioning-daemon\n\n# List current configurations\n./provisioning/scripts/setup-platform-config.sh --list-configs\n# Output: Shows current runtime configurations and their status\n\n# Clean all runtime configurations (use with caution)\n./provisioning/scripts/setup-platform-config.sh --clean\n# Removes: provisioning/config/runtime/*.ncl\n#          provisioning/config/runtime/generated/*.toml\n```\n\n## Configuration File Locations\n\n### Public Definitions (Part of repository)\n\n```\nprovisioning/schemas/platform/\n├── schemas/              # Type contracts (Nickel)\n├── defaults/             # Base configuration values\n│   └── deployment/       # Mode-specific: solo, multiuser, cicd, enterprise\n├── validators/           # Business logic validation\n├── templates/            # Configuration generation templates\n└── constraints/          # Validation limits\n```\n\n### Private Runtime Configs (Gitignored)\n\n```\nprovisioning/config/runtime/              # User-specific deployments\n├── orchestrator.solo.ncl                 # Editable config\n├── orchestrator.multiuser.ncl\n└── generated/                            # Auto-generated, don't edit\n    ├── orchestrator.solo.toml            # For Rust services\n    └── orchestrator.multiuser.toml\n```\n\n### Examples (Reference)\n\n```\nprovisioning/config/examples/\n├── orchestrator.solo.example.ncl         # Solo mode reference\n└── orchestrator.enterprise.example.ncl   # Enterprise mode reference\n```\n\n## Troubleshooting Configuration\n\n### Issue: Script Fails with "Nickel not found"\n\n```\n# Install Nickel\n# macOS\nbrew install nickel\n\n# Linux\ncargo install nickel --version 0.10\n\n# Verify installation\nnickel --version\n# Expected: 0.10.0 or higher\n```\n\n### Issue: Configuration Won't Generate TOML\n\n```\n# Check Nickel syntax\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# If errors found, view detailed message\nnickel typecheck -i provisioning/config/runtime/orchestrator.solo.ncl\n\n# Try manual export\nnickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl\n```\n\n### Issue: Service Can't Read Configuration\n\n```\n# Verify TOML file exists\nls -la provisioning/config/runtime/generated/orchestrator.solo.toml\n\n# Verify file is valid TOML\nhead -20 provisioning/config/runtime/generated/orchestrator.solo.toml\n\n# Check service is looking in right location\necho $ORCHESTRATOR_MODE  # Should be set to 'solo', 'multiuser', etc.\n\n# Verify environment variable is correct\nexport ORCHESTRATOR_MODE=solo\ncargo run -p orchestrator --verbose\n```\n\n### Issue: Services Won't Start After Config Change\n\n```\n# If you edited .ncl file manually, TOML must be regenerated\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n\n# Verify new TOML was created\nstat provisioning/config/runtime/generated/orchestrator.solo.toml\n\n# Check modification time (should be recent)\nls -lah provisioning/config/runtime/generated/orchestrator.solo.toml\n```\n\n## Important Notes\n\n### 🔒 Runtime Configurations Are Private\n\nFiles in `provisioning/config/runtime/` are **gitignored** because:\n- May contain encrypted secrets or credentials\n- Deployment-specific (different per environment)\n- User-customized (each developer/machine has different needs)\n\n### 📘 Schemas Are Public\n\nFiles in `provisioning/schemas/platform/` are **version-controlled** because:\n- Define product structure and constraints\n- Part of official releases\n- Source of truth for configuration format\n- Shared across the team\n\n### 🔄 Configuration Is Idempotent\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 without --clean\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n\n# Only deletes on explicit request\n./provisioning/scripts/setup-platform-config.sh --clean\n```\n\n### ⚠️ Installer Status\n\nThe full provisioning installer (`provisioning/scripts/install.sh`) is **not yet implemented**. Currently:\n\n- ✅ Configuration setup script is standalone and ready to use\n- ⏳ Full installer integration is planned for future release\n- ✅ Manual workflow works perfectly without installer\n- ✅ CI/CD integration available now\n\n## Next Steps\n\nAfter completing platform configuration:\n\n1. **Run Services**: Start your platform services with configured settings\n2. **Access Web UI**: Open Control Center at [http://localhost:8080](http://localhost:8080) (default)\n3. **Create First Infrastructure**: Deploy your first servers and clusters\n4. **Set Up Extensions**: Configure providers and task services for your needs\n5. **Backup Configuration**: Back up runtime configs to private repository\n\n## Additional Resources\n\n- [Setup Status & Current System Status](../../provisioning/config/SETUP_STATUS.md) - Quick reference for system readiness\n- [Configuration README](../../provisioning/config/README.md) - Detailed configuration management guide\n- [Setup Script Documentation](../../provisioning/scripts/setup-platform-config.sh.md) - Complete script reference\n- [TypeDialog Platform Config Guide](../development/typedialog-platform-config-guide.md) - Advanced configuration topics\n- [Deployment Guide](../operations/deployment-guide.md) - Production deployment procedures\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2026-01-05\n**Difficulty**: Beginner to Intermediate
