1 line
12 KiB
Markdown
1 line
12 KiB
Markdown
# Example Platform Service Configurations\n\nThis directory contains reference configurations for platform services in different deployment modes. These examples show realistic settings and best practices for each mode.\n\n## What Are These Examples?\n\nThese are **Nickel configuration files** (.ncl format) that demonstrate how to configure the provisioning platform services. They show:\n\n- Recommended settings for each deployment mode\n- How to customize services for your environment\n- Best practices for development, staging, and production\n- Performance tuning for different scenarios\n- Security settings appropriate to each mode\n\n## Directory Structure\n\n```\nprovisioning/config/examples/\n├── README.md # This file\n├── orchestrator.solo.example.ncl # Development mode reference\n├── orchestrator.multiuser.example.ncl # Team staging reference\n└── orchestrator.enterprise.example.ncl # Production reference\n```\n\n## Deployment Modes\n\n### Solo Mode (Development)\n\n**File**: `orchestrator.solo.example.ncl`\n\n**Characteristics**:\n- 2 CPU, 4GB RAM (lightweight)\n- Single user/developer\n- Local development machine\n- Minimal resource consumption\n- No TLS or authentication\n- In-memory storage\n\n**When to use**:\n- Local development\n- Testing configurations\n- Learning the platform\n- CI/CD test environments\n\n**Key Settings**:\n- workers: 2\n- max_concurrent_tasks: 2\n- max_memory: 1GB\n- tls: disabled\n- auth: disabled\n\n### Multiuser Mode (Team Staging)\n\n**File**: `orchestrator.multiuser.example.ncl`\n\n**Characteristics**:\n- 4 CPU, 8GB RAM (moderate)\n- Multiple concurrent users\n- Team staging environment\n- Production-like testing\n- Basic TLS and token auth\n- Filesystem storage with caching\n\n**When to use**:\n- Team development\n- Integration testing\n- Staging environment\n- Pre-production validation\n- Multi-user environments\n\n**Key Settings**:\n- workers: 4\n- max_concurrent_tasks: 10\n- max_memory: 4GB\n- tls: enabled (certificates required)\n- auth: token-based\n- storage: filesystem with replication\n\n### Enterprise Mode (Production)\n\n**File**: `orchestrator.enterprise.example.ncl`\n\n**Characteristics**:\n- 16+ CPU, 32+ GB RAM (high-performance)\n- Multi-team, multi-workspace\n- Production mission-critical\n- Full redundancy and HA\n- OAuth2/Enterprise auth\n- Distributed storage with replication\n- Full monitoring, tracing, audit\n\n**When to use**:\n- Production deployment\n- Mission-critical systems\n- High-availability requirements\n- Multi-tenant environments\n- Compliance requirements (SOC2, ISO27001)\n\n**Key Settings**:\n- workers: 16\n- max_concurrent_tasks: 100\n- max_memory: 32GB\n- tls: mandatory (TLS 1.3)\n- auth: OAuth2 (enterprise provider)\n- storage: distributed with 3-way replication\n- monitoring: comprehensive with tracing\n- disaster_recovery: enabled\n- compliance: SOC2, ISO27001\n\n## How to Use These Examples\n\n### Step 1: Copy the Appropriate Example\n\nChoose the example that matches your deployment mode:\n\n```\n# For development (solo)\ncp provisioning/config/examples/orchestrator.solo.example.ncl \n provisioning/config/runtime/orchestrator.solo.ncl\n\n# For team staging (multiuser)\ncp provisioning/config/examples/orchestrator.multiuser.example.ncl \n provisioning/config/runtime/orchestrator.multiuser.ncl\n\n# For production (enterprise)\ncp provisioning/config/examples/orchestrator.enterprise.example.ncl \n provisioning/config/runtime/orchestrator.enterprise.ncl\n```\n\n### Step 2: Customize for Your Environment\n\nEdit the copied file to match your specific setup:\n\n```\n# Edit the configuration\nvim provisioning/config/runtime/orchestrator.solo.ncl\n\n# Examples of customizations:\n# - Change workspace path to your project\n# - Adjust worker count based on CPU cores\n# - Set your domain names and hostnames\n# - Configure storage paths for your filesystem\n# - Update certificate paths for production\n# - Set logging endpoints for your infrastructure\n```\n\n### Step 3: Validate Configuration\n\nVerify the configuration is syntactically correct:\n\n```\n# Check Nickel syntax\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# View generated TOML\nnickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl\n```\n\n### Step 4: Generate TOML\n\nExport the Nickel configuration to TOML format for service consumption:\n\n```\n# Use setup script to generate TOML\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n\n# Or manually export\nnickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl > \n provisioning/config/runtime/generated/orchestrator.solo.toml\n```\n\n### Step 5: Run Services\n\nStart your platform services with the generated configuration:\n\n```\n# Set the deployment mode\nexport ORCHESTRATOR_MODE=solo\n\n# Run the orchestrator\ncargo run -p orchestrator\n```\n\n## Configuration Reference\n\n### Solo Mode Example Settings\n\n```\nserver.workers = 2\nqueue.max_concurrent_tasks = 2\nperformance.max_memory = 1000 # 1GB max\nsecurity.tls.enabled = false # No TLS for local dev\nsecurity.auth.enabled = false # No auth for local dev\n```\n\n**Use case**: Single developer on local machine\n\n### Multiuser Mode Example Settings\n\n```\nserver.workers = 4\nqueue.max_concurrent_tasks = 10\nperformance.max_memory = 4000 # 4GB max\nsecurity.tls.enabled = true # Enable TLS\nsecurity.auth.type = "token" # Token-based auth\n```\n\n**Use case**: Team of 5-10 developers in staging\n\n### Enterprise Mode Example Settings\n\n```\nserver.workers = 16\nqueue.max_concurrent_tasks = 100\nperformance.max_memory = 32000 # 32GB max\nsecurity.tls.enabled = true # TLS 1.3 only\nsecurity.auth.type = "oauth2" # OAuth2 for enterprise\nstorage.replication.factor = 3 # 3-way replication\n```\n\n**Use case**: Production with 100+ users across multiple teams\n\n## Key Configuration Sections\n\n### Server Configuration\n\nControls HTTP server behavior:\n\n```\nserver = {\n host = "0.0.0.0", # Bind address\n port = 9090, # Listen port\n workers = 4, # Worker threads\n max_connections = 200, # Concurrent connections\n request_timeout = 30000, # Milliseconds\n}\n```\n\n### Storage Configuration\n\nControls data persistence:\n\n```\nstorage = {\n backend = "filesystem", # filesystem or distributed\n path = "/var/lib/provisioning/orchestrator/data",\n cache.enabled = true,\n replication.enabled = true,\n replication.factor = 3, # 3-way replication for HA\n}\n```\n\n### Queue Configuration\n\nControls task queuing:\n\n```\nqueue = {\n max_concurrent_tasks = 10,\n retry_attempts = 3,\n task_timeout = 3600000, # 1 hour in milliseconds\n priority_queue = true, # Enable priority for tasks\n metrics = true, # Enable queue metrics\n}\n```\n\n### Security Configuration\n\nControls authentication and encryption:\n\n```\nsecurity = {\n tls = {\n enabled = true,\n cert_path = "/etc/provisioning/certs/cert.crt",\n key_path = "/etc/provisioning/certs/key.key",\n min_tls_version = "1.3",\n },\n auth = {\n enabled = true,\n type = "oauth2", # oauth2, token, or none\n provider = "okta",\n },\n encryption = {\n enabled = true,\n algorithm = "aes-256-gcm",\n },\n}\n```\n\n### Logging Configuration\n\nControls log output and persistence:\n\n```\nlogging = {\n level = "info", # debug, info, warning, error\n format = "json",\n output = "both", # stdout, file, or both\n file = {\n enabled = true,\n path = "/var/log/orchestrator.log",\n rotation.max_size = 104857600, # 100MB per file\n },\n}\n```\n\n### Monitoring Configuration\n\nControls observability and metrics:\n\n```\nmonitoring = {\n enabled = true,\n metrics.enabled = true,\n health_check.enabled = true,\n distributed_tracing.enabled = true,\n audit_logging.enabled = true,\n}\n```\n\n## Customization Examples\n\n### Example 1: Change Workspace Name\n\nChange the workspace identifier in solo mode:\n\n```\nworkspace = {\n name = "myproject",\n path = "./provisioning/data/orchestrator",\n}\n```\n\nInstead of default "development", use "myproject".\n\n### Example 2: Custom Server Port\n\nChange server port from default 9090:\n\n```\nserver = {\n port = 8888,\n}\n```\n\nUseful if port 9090 is already in use.\n\n### Example 3: Enable TLS in Solo Mode\n\nAdd TLS certificates to solo development:\n\n```\nsecurity = {\n tls = {\n enabled = true,\n cert_path = "./certs/localhost.crt",\n key_path = "./certs/localhost.key",\n },\n}\n```\n\nUseful for testing TLS locally before production.\n\n### Example 4: Custom Storage Path\n\nUse custom storage location:\n\n```\nstorage = {\n path = "/mnt/fast-storage/orchestrator/data",\n}\n```\n\nUseful if you have fast SSD storage available.\n\n### Example 5: Increase Workers for Staging\n\nIncrease from 4 to 8 workers in multiuser:\n\n```\nserver = {\n workers = 8,\n}\n```\n\nUseful when you have more CPU cores available.\n\n## Troubleshooting Configuration\n\n### Issue: "Configuration Won't Validate"\n\n```\n# Check for Nickel syntax errors\nnickel typecheck provisioning/config/runtime/orchestrator.solo.ncl\n\n# Get detailed error message\nnickel typecheck -i provisioning/config/runtime/orchestrator.solo.ncl\n```\n\nThe typecheck command will show exactly where the syntax error is.\n\n### Issue: "Service Won't Start"\n\n```\n# Verify TOML was exported correctly\ncat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20\n\n# Check TOML syntax is valid\ntoml-cli validate provisioning/config/runtime/generated/orchestrator.solo.toml\n```\n\nThe TOML must be valid for the Rust service to parse it.\n\n### Issue: "Service Uses Wrong Configuration"\n\n```\n# Verify deployment mode is set\necho $ORCHESTRATOR_MODE\n\n# Check which TOML file service reads\nls -lah provisioning/config/runtime/generated/orchestrator.*.toml\n\n# Verify TOML modification time is recent\nstat provisioning/config/runtime/generated/orchestrator.solo.toml\n```\n\nThe service reads from `orchestrator.{MODE}.toml` based on environment variable.\n\n## Best Practices\n\n### Development (Solo Mode)\n\n1. Start simple using the solo example as-is first\n2. Iterate gradually, making one change at a time\n3. Enable logging by setting level = "debug" for troubleshooting\n4. Disable security features for local development (TLS/auth)\n5. Store data in ./provisioning/data/ which is gitignored\n\n### Staging (Multiuser Mode)\n\n1. Mirror production settings to test realistically\n2. Enable authentication even in staging to test auth flows\n3. Enable TLS with valid certificates to test secure connections\n4. Set up monitoring metrics and health checks\n5. Plan worker count based on expected concurrent users\n\n### Production (Enterprise Mode)\n\n1. Follow the enterprise example as baseline configuration\n2. Use secure vault for storing credentials and secrets\n3. Enable redundancy with 3-way replication for HA\n4. Enable full monitoring with distributed tracing\n5. Test failover scenarios regularly\n6. Enable audit logging for compliance\n7. Enforce TLS 1.3 and certificate rotation\n\n## Migration Between Modes\n\nTo upgrade from solo → multiuser → enterprise:\n\n```\n# 1. Backup current configuration\ncp provisioning/config/runtime/orchestrator.solo.ncl \n provisioning/config/runtime/orchestrator.solo.ncl.bak\n\n# 2. Copy new example for target mode\ncp provisioning/config/examples/orchestrator.multiuser.example.ncl \n provisioning/config/runtime/orchestrator.multiuser.ncl\n\n# 3. Customize for your environment\nvim provisioning/config/runtime/orchestrator.multiuser.ncl\n\n# 4. Validate and generate TOML\n./provisioning/scripts/setup-platform-config.sh --generate-toml\n\n# 5. Update mode environment variable and restart\nexport ORCHESTRATOR_MODE=multiuser\ncargo run -p orchestrator\n```\n\n## Related Documentation\n\n- **Platform Configuration Guide**: `provisioning/docs/src/getting-started/05-platform-configuration.md`\n- **Configuration README**: `provisioning/config/README.md`\n- **System Status**: `provisioning/config/SETUP_STATUS.md`\n- **Setup Script Reference**: `provisioning/scripts/setup-platform-config.sh.md`\n- **Advanced TypeDialog Guide**: `provisioning/docs/src/development/typedialog-platform-config-guide.md`\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2026-01-05\n**Status**: Ready to use |