2 lines
28 KiB
Markdown
2 lines
28 KiB
Markdown
# Provisioning Platform Configuration Examples\n\nProduction-ready reference configurations demonstrating different deployment scenarios and best practices.\n\n## Purpose\n\nExamples provide:\n- **Real-world configurations** - Complete, tested working setups ready for production use\n- **Best practices** - Recommended patterns, values, and architectural approaches\n- **Learning resource** - How to use the configuration system effectively\n- **Starting point** - Copy, customize, and deploy for your environment\n- **Documentation** - Detailed inline comments explaining every configuration option\n\n## Quick Start\n\nChoose your deployment mode and get started immediately:\n\n```\n# Solo development (local, single developer)\nnickel export --format toml orchestrator-solo.ncl > orchestrator.toml\n\n# Team collaboration (PostgreSQL, RBAC, audit logging)\nnickel export --format toml control-center-multiuser.ncl > control-center.toml\n\n# Production enterprise (HA, SurrealDB cluster, full monitoring)\nnickel export --format toml full-platform-enterprise.ncl > platform.toml\n```\n\n## Example Configurations by Mode\n\n### 1. orchestrator-solo.ncl\n\n**Deployment Mode**: Solo (Single Developer)\n\n**Resource Requirements**:\n- CPU: 2 cores\n- RAM: 4 GB\n- Disk: 50 GB (local data)\n\n**Configuration Highlights**:\n- **Workspace**: Local `dev-workspace` at `/home/developer/provisioning/data/orchestrator`\n- **Server**: Localhost binding (127.0.0.1:9090), 2 workers, 128 connections max\n- **Storage**: Filesystem backend (no external database required)\n- **Queue**: 3 max concurrent tasks (minimal for development)\n- **Batch**: 2 parallel limit with frequent checkpointing (every 50 operations)\n- **Logging**: Debug level, human-readable text format, concurrent stdout + file output\n- **Security**: Auth disabled, CORS allows all origins, no TLS\n- **Monitoring**: Health checks only (metrics disabled), resource tracking disabled\n- **Features**: Experimental features enabled for testing and iteration\n\n**Ideal For**:\n- ✅ Single developer local development\n- ✅ Quick prototyping and experimentation\n- ✅ Learning the provisioning platform\n- ✅ CI/CD local testing without external services\n\n**Key Advantages**:\n- No external dependencies (database-free)\n- Fast startup (<10 seconds)\n- Minimal resource footprint\n- Verbose debug logging for troubleshooting\n- Zero security overhead\n\n**Key Limitations**:\n- Localhost-only (not accessible remotely)\n- Single-threaded processing (3 concurrent tasks max)\n- No persistence across restarts (if using `:memory:` storage)\n- No audit logging\n\n**Usage**:\n\n```\n# Export to TOML and run\nnickel export --format toml orchestrator-solo.ncl > orchestrator.solo.toml\nORCHESTRATOR_CONFIG=orchestrator.solo.toml cargo run --bin orchestrator\n\n# With TypeDialog interactive configuration\nnu ../../scripts/configure.nu orchestrator solo --backend cli\n```\n\n**Customization Examples**:\n\n```\n# Increase concurrency for testing (still development-friendly)\nqueue.max_concurrent_tasks = 5\n\n# Reduce debug noise for cleaner logs\nlogging.level = "info"\n\n# Change workspace location\nworkspace.path = "/path/to/my/workspace"\n```\n\n---\n\n### 2. orchestrator-enterprise.ncl\n\n**Deployment Mode**: Enterprise (Production High-Availability)\n\n**Resource Requirements**:\n- CPU: 8+ cores (recommended 16)\n- RAM: 16+ GB (recommended 32+ GB)\n- Disk: 500+ GB (SurrealDB cluster)\n\n**Configuration Highlights**:\n- **Workspace**: Production `production` workspace at `/var/lib/provisioning/orchestrator` with multi-workspace support enabled\n- **Server**: All interfaces binding (0.0.0.0:9090), 16 workers, 4096 connections max\n- **Storage**: SurrealDB cluster (3 nodes) for distributed storage and high availability\n- **Queue**: 100 max concurrent tasks, 5 retry attempts, 2-hour timeout for long-running operations\n- **Batch**: 50 parallel limit with frequent checkpointing (every 1000 operations) and automatic cleanup\n- **Logging**: Info level, JSON structured format for log aggregation\n - Standard logs: 500MB files, kept 30 versions (90 days)\n - Audit logs: 200MB files, kept 365 versions (1 year)\n- **Security**: JWT authentication required, specific CORS origins, TLS 1.3 mandatory, 10,000 RPS rate limit\n- **Extensions**: Auto-load from OCI registry with daily refresh, 10 concurrent initializations\n- **Monitoring**:\n - Metrics every 10 seconds\n - Profiling at 10% sample rate\n - Resource tracking with CPU/memory/disk alerts\n - Health checks every 30 seconds\n- **Features**: Audit logging, task history, performance tracking all enabled\n\n**Ideal For**:\n- ✅ Production deployments with SLAs\n- ✅ High-throughput, mission-critical workloads\n- ✅ Multi-team environments requiring audit trails\n- ✅ Large-scale infrastructure deployments\n- ✅ Compliance and governance requirements\n\n**Key Advantages**:\n- High availability (3 SurrealDB replicas with failover)\n- Production security (JWT + TLS 1.3 mandatory)\n- Full observability (metrics, profiling, audit logs)\n- High throughput (100 concurrent tasks)\n- Extension management via OCI registry\n- Automatic rollback and recovery capabilities\n\n**Key Limitations**:\n- Requires SurrealDB cluster setup and maintenance\n- Resource-intensive (8+ CPU, 16+ GB RAM minimum)\n- More complex initial setup and configuration\n- Requires secrets management (JWT keys, TLS certificates)\n- Network isolation and load balancing setup required\n\n**Environment Variables Required**:\n\n```\nexport JWT_SECRET="<secure-random-256-bit-string>"\nexport SURREALDB_PASSWORD="<database-password>"\n```\n\n**Usage**:\n\n```\n# Deploy standalone with SurrealDB\nnickel export --format toml orchestrator-enterprise.ncl > orchestrator.enterprise.toml\nORCHESTRATOR_CONFIG=orchestrator.enterprise.toml cargo run --bin orchestrator\n\n# Deploy to Kubernetes with all enterprise infrastructure\nnu ../../scripts/render-kubernetes.nu enterprise --namespace production\nkubectl apply -f provisioning/platform/infrastructure/kubernetes/*.yaml\n```\n\n**Customization Examples**:\n\n```\n# Adjust concurrency for your specific infrastructure\nqueue.max_concurrent_tasks = 50 # Scale down if resource-constrained\n\n# Change SurrealDB cluster endpoints\nstorage.surrealdb_url = "surrealdb://node1:8000,node2:8000,node3:8000"\n\n# Modify audit log retention for compliance\nlogging.outputs[1].rotation.max_backups = 2555 # 7 years for HIPAA compliance\n\n# Increase rate limiting for high-frequency integrations\nsecurity.rate_limit.requests_per_second = 20000\n```\n\n---\n\n### 3. control-center-multiuser.ncl\n\n**Deployment Mode**: MultiUser (Team Collaboration & Staging)\n\n**Resource Requirements**:\n- CPU: 4 cores\n- RAM: 8 GB\n- Disk: 100 GB (PostgreSQL data + logs)\n\n**Configuration Highlights**:\n- **Server**: All interfaces binding (0.0.0.0:8080), 4 workers, 256 connections max\n- **Database**: PostgreSQL with connection pooling (min 5, max 20 connections)\n- **Auth**: JWT with 8-hour token expiration (aligned with team workday)\n- **RBAC**: 4 pre-defined roles with granular permissions\n - `admin`: Infrastructure lead with full access (`*` permissions)\n - `operator`: Operations team - execute, manage, view workflows and policies\n - `developer`: Development team - read-only workflow and policy access\n - `viewer`: Minimal read-only for non-technical stakeholders\n- **MFA**: Optional per-user (TOTP + email methods available, not globally required)\n- **Password Policies**: 12-character minimum, requires uppercase/lowercase/digits, 90-day rotation, history count of 3\n- **Session Policies**: 8-hour maximum duration, 1-hour idle timeout, 3 concurrent sessions per user\n- **Rate Limiting**: 1000 RPS global, 100 RPS per-user, 20 burst requests\n- **CORS**: Allows localhost:3000 (dev), control-center.example.com, orchestrator.example.com\n- **Logging**: Info level, JSON format, 200MB files kept 15 versions (90 days retention)\n- **Features**: Audit logging enabled, policy enforcement enabled\n\n**Ideal For**:\n- ✅ Team collaboration (2-50 engineers)\n- ✅ Staging environments before production\n- ✅ Development team operations\n- ✅ RBAC with different access levels\n- ✅ Compliance-light environments (SOC2 optional)\n\n**Key Advantages**:\n- Team-friendly security (optional MFA, reasonable password policy)\n- RBAC supports different team roles and responsibilities\n- Persistent storage (PostgreSQL) maintains state across restarts\n- Audit trail for basic compliance\n- Flexible session management (multiple concurrent sessions)\n- Good balance of security and usability\n\n**Key Limitations**:\n- Requires PostgreSQL database setup\n- Single replica (not HA by default)\n- More complex than solo mode\n- RBAC requires careful role definition\n\n**Environment Variables Required**:\n\n```\nexport DB_PASSWORD="<postgresql-password>"\nexport JWT_SECRET="<secure-random-string>"\n```\n\n**Usage**:\n\n```\n# Generate and deploy\nnickel export --format toml control-center-multiuser.ncl > control-center.multiuser.toml\nCONTROL_CENTER_CONFIG=control-center.multiuser.toml cargo run --bin control-center\n\n# With Docker Compose for team\nnu ../../scripts/render-docker-compose.nu multiuser\ndocker-compose -f docker-compose.multiuser.yml up -d\n\n# Access the UI\n# http://localhost:8080 (or your configured domain)\n```\n\n**RBAC Quick Reference**:\n\n| Role | Intended Users | Key Permissions |\n| ------ | ---------------- | ----------------- |\n| admin | Infrastructure leads | All operations: full access |\n| operator | Operations engineers | Execute workflows, manage tasks, view policies |\n| developer | Application developers | View workflows, view policies (read-only) |\n| viewer | Non-technical (PM, QA) | View workflows only (minimal read) |\n\n**Customization Examples**:\n\n```\n# Require MFA globally for higher security\nmfa.required = true\n\n# Add custom role for auditors\nrbac.roles.auditor = {\n description = "Compliance auditor",\n permissions = ["audit.view", "orchestrator.view"],\n}\n\n# Adjust for larger team (more concurrent sessions)\npolicies.session.max_concurrent = 5\n\n# Stricter password policy for regulated industry\npolicies.password = {\n min_length = 16,\n require_special_chars = true,\n expiration_days = 60,\n history_count = 8,\n}\n```\n\n---\n\n### 4. full-platform-enterprise.ncl\n\n**Deployment Mode**: Enterprise Integrated (Complete Platform)\n\n**Resource Requirements**:\n- CPU: 16+ cores (3 replicas × 4 cores each + infrastructure)\n- RAM: 32+ GB (orchestrator 12GB + control-center 4GB + databases 12GB + monitoring 4GB)\n- Disk: 1+ TB (databases, logs, metrics, artifacts)\n\n**Services Configured**:\n\n**Orchestrator Section**:\n- SurrealDB cluster (3 nodes) for distributed workflow storage\n- 100 concurrent tasks with 5 retry attempts\n- Full audit logging and monitoring\n- JWT authentication with configurable token expiration\n- Extension loading from OCI registry\n- High-performance tuning (16 workers, 4096 connections)\n\n**Control Center Section**:\n- PostgreSQL HA backend for policy/RBAC storage\n- Full RBAC (4 roles with 7+ permissions each)\n- MFA required (TOTP + email methods)\n- SOC2 compliance enabled with audit logging\n- Strict password policy (16+ chars, special chars required)\n- 30-minute session idle timeout for security\n- Per-user rate limiting (100 RPS)\n\n**MCP Server Section**:\n- Claude integration for AI-powered provisioning\n- Full MCP capability support (tools, resources, prompts, sampling)\n- Orchestrator and Control Center integration\n- Read-only filesystem access with 10MB file limit\n- JWT authentication\n- Advanced audit logging (all requests logged except sensitive data)\n- 100 RPS rate limiting with 20-request burst\n\n**Global Configuration**:\n\n```\nlet deployment_mode = "enterprise"\nlet namespace = "provisioning"\nlet domain = "provisioning.example.com"\nlet environment = "production"\n```\n\n**Infrastructure Components** (when deployed to Kubernetes):\n- Load Balancer (Nginx) - TLS termination, CORS, rate limiting\n- 3x Orchestrator replicas - Distributed processing\n- 2x Control Center replicas - Policy management\n- 1-2x MCP Server replicas - AI integration\n- PostgreSQL HA - Primary/replica setup\n- SurrealDB cluster - 3 nodes with replication\n- Prometheus - Metrics collection\n- Grafana - Visualization and dashboards\n- Loki - Log aggregation\n- Harbor - Private OCI image registry\n\n**Ideal For**:\n- ✅ Production deployments with full SLAs\n- ✅ Enterprise compliance requirements (SOC2, HIPAA)\n- ✅ Multi-team organizations\n- ✅ AI/LLM integration for provisioning\n- ✅ Large-scale infrastructure management (1000+ resources)\n- ✅ High-availability deployments with 99.9%+ uptime requirements\n\n**Key Advantages**:\n- Complete service integration (no missing pieces)\n- Production-grade HA setup (3 replicas, load balancing)\n- Full compliance and audit capabilities\n- AI/LLM integration via MCP Server\n- Comprehensive monitoring and observability\n- Clear separation of concerns per service\n- Global variables for easy parameterization\n\n**Key Limitations**:\n- Complex setup requiring multiple services\n- Resource-intensive (16+ CPU, 32+ GB RAM minimum)\n- Requires Kubernetes or advanced Docker Compose setup\n- Multiple databases to maintain (PostgreSQL + SurrealDB)\n- Network setup complexity (TLS, CORS, rate limiting)\n\n**Environment Variables Required**:\n\n```\n# Database credentials\nexport DB_PASSWORD="<postgresql-password>"\nexport SURREALDB_PASSWORD="<surrealdb-password>"\n\n# Security\nexport JWT_SECRET="<secure-random-256-bit-string>"\nexport KMS_KEY="<kms-encryption-key-for-secrets>"\n\n# AI/LLM integration\nexport CLAUDE_API_KEY="<anthropic-api-key>"\nexport CLAUDE_MODEL="claude-3-opus-20240229"\n\n# TLS certificates (for production)\nexport TLS_CERT="<certificate-path>"\nexport TLS_KEY="<key-path>"\n```\n\n**Architecture Diagram**:\n\n```\n┌───────────────────────────────────────────────┐\n│ Nginx Load Balancer (TLS, CORS, RateLimit) │\n│ https://orchestrator.example.com │\n│ https://control-center.example.com │\n│ https://mcp.example.com │\n└──────────┬──────────────────────┬─────────────┘\n │ │\n ┌──────▼──────┐ ┌────────▼────────┐\n │ Orchestrator│ │ Control Center │\n │ (3 replicas)│ │ (2 replicas) │\n └──────┬──────┘ └────────┬────────┘\n │ │\n ┌──────▼──────┐ ┌────────▼────────┐ ┌─────────────────┐\n │ SurrealDB │ │ PostgreSQL HA │ │ MCP Server │\n │ Cluster │ │ │ │ (1-2 replicas) │\n │ (3 nodes) │ │ Primary/Replica│ │ │\n └─────────────┘ └─────────────────┘ │ ↓ Claude API │\n └─────────────────┘\n\n ┌─────────────────────────────────────────────────┐\n │ Observability Stack (Optional) │\n ├──────────────────┬──────────────────────────────┤\n │ Prometheus │ Grafana │ Loki │\n │ (Metrics) │ (Dashboards) │ (Logs) │\n └──────────────────┴──────────────────────────────┘\n```\n\n**Usage**:\n\n```\n# Export complete configuration\nnickel export --format toml full-platform-enterprise.ncl > platform.toml\n\n# Extract individual service configs if needed\n# (Each service extracts its section from platform.toml)\n\n# Deploy to Kubernetes with all enterprise infrastructure\nnu ../../scripts/render-kubernetes.nu enterprise --namespace production\n\n# Apply all manifests\nkubectl create namespace production\nkubectl apply -f provisioning/platform/infrastructure/kubernetes/*.yaml\n\n# Or deploy with Docker Compose for single-node testing\nnu ../../scripts/render-docker-compose.nu enterprise\ndocker-compose -f docker-compose.enterprise.yml up -d\n```\n\n**Customization Examples**:\n\n```\n# Adjust deployment domain\nlet domain = "my-company.com"\nlet namespace = "infrastructure"\n\n# Scale for higher throughput\norchestrator.queue.max_concurrent_tasks = 200\norchestrator.security.rate_limit.requests_per_second = 50000\n\n# Add HIPAA compliance\ncontrol_center.policies.compliance.hipaa.enabled = true\ncontrol_center.policies.audit.retention_days = 2555 # 7 years\n\n# Custom MCP Server model\nmcp_server.integration.claude.model = "claude-3-sonnet-20240229"\n\n# Enable caching for performance\nmcp_server.features.enable_caching = true\nmcp_server.performance.cache_ttl = 7200\n```\n\n---\n\n## Deployment Mode Comparison Matrix\n\n| Feature | Solo | MultiUser | Enterprise |\n| --------- | ------ | ----------- | ----------- |\n| **Ideal For** | Dev | Team/Staging | Production |\n| **Storage** | Filesystem | PostgreSQL | SurrealDB Cluster |\n| **Replicas** | 1 | 1 | 3+ (HA) |\n| **Max Concurrency** | 3 tasks | 5-10 | 100 |\n| **Security** | None | RBAC + JWT | Full + MFA + SOC2 |\n| **Monitoring** | Health check | Basic | Full (Prom+Grafana) |\n| **Setup Time** | <5 min | 15 min | 30+ min |\n| **Min CPU** | 2 | 4 | 16 |\n| **Min RAM** | 4GB | 8GB | 32GB |\n| **Audit Logs** | No | 90 days | 365 days |\n| **TLS Required** | No | No | Yes |\n| **Compliance** | None | Basic | SOC2 + HIPAA ready |\n\n---\n\n## Getting Started Guide\n\n### Step 1: Choose Your Deployment Mode\n\n- **Solo**: Single developer working locally → Use `orchestrator-solo.ncl`\n- **Team**: 2-50 engineers, staging environment → Use `control-center-multiuser.ncl`\n- **Production**: Full enterprise deployment → Use `full-platform-enterprise.ncl`\n\n### Step 2: Export Configuration to TOML\n\n```\n# Start with solo mode\nnickel export --format toml orchestrator-solo.ncl > orchestrator.toml\n\n# Validate the export\ncat orchestrator.toml | head -20\n```\n\n### Step 3: Validate Configuration\n\n```\n# Typecheck the Nickel configuration\nnickel typecheck orchestrator-solo.ncl\n\n# Validate using provided script\nnu ../../scripts/validate-config.nu orchestrator-solo.ncl\n```\n\n### Step 4: Customize for Your Environment\n\nEdit the exported `.toml` or the `.ncl` file:\n\n```\n# Option A: Edit TOML directly (simpler)\nvi orchestrator.toml # Change workspace path, port, etc.\n\n# Option B: Edit Nickel and re-export (type-safe)\nvi orchestrator-solo.ncl\nnickel export --format toml orchestrator-solo.ncl > orchestrator.toml\n```\n\n### Step 5: Deploy\n\n```\n# Docker Compose\nORCHESTRATOR_CONFIG=orchestrator.toml docker-compose up -d\n\n# Direct Rust execution\nORCHESTRATOR_CONFIG=orchestrator.toml cargo run --bin orchestrator\n\n# Kubernetes\nnu ../../scripts/render-kubernetes.nu solo\nkubectl apply -f provisioning/platform/infrastructure/kubernetes/*.yaml\n```\n\n---\n\n## Common Customizations\n\n### Changing Domain/Namespace\n\nIn any `.ncl` file at the top:\n\n```\nlet domain = "your-domain.com"\nlet namespace = "your-namespace"\nlet environment = "your-env"\n```\n\n### Increasing Resource Limits\n\nFor higher throughput:\n\n```\nqueue.max_concurrent_tasks = 200 # Default: 100\nsecurity.rate_limit.requests_per_second = 50000 # Default: 10000\nserver.workers = 32 # Default: 16\n```\n\n### Enabling Compliance Features\n\nFor regulated environments:\n\n```\npolicies.compliance.soc2.enabled = true\npolicies.compliance.hipaa.enabled = true\npolicies.audit.retention_days = 2555 # 7 years\n```\n\n### Custom Logging\n\nFor troubleshooting:\n\n```\nlogging.level = "debug" # Default: info\nlogging.format = "text" # Default: json (use text for development)\nlogging.outputs[0].level = "debug" # stdout level\n```\n\n---\n\n## Validation & Testing\n\n### Syntax Validation\n\n```\n# Typecheck all examples\nfor f in *.ncl; do\n echo "Checking $f..."\n nickel typecheck "$f"\ndone\n```\n\n### Configuration Export\n\n```\n# Export to TOML\nnickel export --format toml orchestrator-solo.ncl | head -30\n\n# Export to JSON\nnickel export --format json full-platform-enterprise.ncl | jq '.orchestrator.server'\n```\n\n### Load in Rust Application\n\n```\n# With dry-run flag (if supported)\nORCHESTRATOR_CONFIG=orchestrator.solo.toml cargo run --bin orchestrator -- --validate\n\n# Or simply attempt startup\nORCHESTRATOR_CONFIG=orchestrator.solo.toml timeout 5 cargo run --bin orchestrator\n```\n\n---\n\n## Troubleshooting\n\n### "Type mismatch" Error\n\n**Cause**: Field value doesn't match expected type\n\n**Fix**: Check the schema for correct type. Common issues:\n- Use `true`/`false` not `"true"`/`"false"` for booleans\n- Use `9090` not `"9090"` for numbers\n- Use record syntax `{ key = value }` not `{ "key": value }`\n\n### Port Already in Use\n\n**Fix**: Change the port in your configuration:\n\n```\nserver.port = 9999 # Instead of 9090\n```\n\n### Database Connection Errors\n\n**Fix**: For multiuser/enterprise modes:\n- Ensure PostgreSQL is running: `docker-compose up -d postgres`\n- Verify credentials in environment variables\n- Check network connectivity\n- Validate connection string format\n\n### Import Not Found\n\n**Fix**: Ensure all relative paths in imports are correct:\n\n```\n# Correct (relative to examples/)\nlet defaults = import "../defaults/orchestrator-defaults.ncl" in\n\n# Wrong (absolute path)\nlet defaults = import "/full/path/to/defaults.ncl" in\n```\n\n---\n\n## Best Practices\n\n1. **Start Small**: Begin with solo mode, graduate to multiuser, then enterprise\n2. **Environment Variables**: Never hardcode secrets, use environment variables\n3. **Version Control**: Keep examples in Git with clear comments\n4. **Validation**: Always typecheck and export before deploying\n5. **Documentation**: Add comments explaining non-obvious configuration choices\n6. **Testing**: Deploy to staging first, validate all services before production\n7. **Monitoring**: Enable metrics and logging from day one for easier troubleshooting\n8. **Backups**: Regular backups of database state and configurations\n\n---\n\n## Adding New Examples\n\n### Create a Custom Example\n\n```\n# Copy an existing example as template\ncp orchestrator-solo.ncl orchestrator-custom.ncl\n\n# Edit for your use case\nvi orchestrator-custom.ncl\n\n# Validate\nnickel typecheck orchestrator-custom.ncl\n\n# Export and test\nnickel export --format toml orchestrator-custom.ncl > orchestrator.custom.toml\n```\n\n### Naming Convention\n\n- **Service + Mode**: `{service}-{mode}.ncl` (orchestrator-solo.ncl)\n- **Scenario**: `{service}-{scenario}.ncl` (orchestrator-high-throughput.ncl)\n- **Full Stack**: `full-platform-{mode}.ncl` (full-platform-enterprise.ncl)\n\n---\n\n## See Also\n\n- **Parent README**: `../README.md` - Complete configuration system overview\n- **Schemas**: `../schemas/` - Type definitions and validation rules\n- **Defaults**: `../defaults/` - Base configurations for composition\n- **Scripts**: `../scripts/` - Automation for configuration workflow\n- **Forms**: `../forms/` - Interactive TypeDialog form definitions\n\n---\n\n**Version**: 2.0\n**Last Updated**: 2025-01-05\n**Status**: Production Ready - All examples tested and validated\n\n## Using Examples\n\n### View Example\n\n```\ncat provisioning/.typedialog/provisioning/platform/examples/orchestrator-solo.ncl\n```\n\n### Copy and Customize\n\n```\n# Start with solo example\ncp examples/orchestrator-solo.ncl values/orchestrator.solo.ncl\n\n# Edit for your environment\nvi values/orchestrator.solo.ncl\n\n# Validate\nnu scripts/validate-config.nu values/orchestrator.solo.ncl\n```\n\n### Generate from Example\n\n```\n# Use example as base, regenerate with TypeDialog\nnu scripts/configure.nu orchestrator solo --backend web\n```\n\n## Example Structure\n\nEach example is a complete Nickel configuration:\n\n```\n# orchestrator-solo.ncl\n{\n orchestrator = {\n workspace = { },\n server = { },\n storage = { },\n queue = { },\n monitoring = { },\n },\n}\n```\n\n## Configuration Elements\n\n### Workspace Configuration\n- **name** - Workspace identifier\n- **path** - Directory path\n- **enabled** - Enable/disable flag\n- **multi_workspace** - Support multiple workspaces\n\n### Server Configuration\n- **host** - Bind address (127.0.0.1 for solo, 0.0.0.0 for public)\n- **port** - Listen port\n- **workers** - Thread count (mode-dependent)\n- **keep_alive** - Connection keep-alive timeout\n- **max_connections** - Connection limit\n\n### Storage Configuration\n- **backend** - 'filesystem | 'rocksdb | 'surrealdb | 'postgres\n- **path** - Local storage path (filesystem/rocksdb)\n- **connection_string** - DB URL (surrealdb/postgres)\n\n### Queue Configuration (Orchestrator)\n- **max_concurrent_tasks** - Concurrent task limit\n- **retry_attempts** - Retry count\n- **retry_delay** - Delay between retries (ms)\n- **task_timeout** - Task execution timeout (ms)\n\n### Monitoring Configuration (Optional)\n- **enabled** - Enable metrics collection\n- **metrics_interval** - Collection frequency (seconds)\n- **health_check_interval** - Health check frequency\n\n## Creating New Examples\n\n### 1. Start with Existing Example\n\n```\ncp examples/orchestrator-solo.ncl examples/orchestrator-custom.ncl\n```\n\n### 2. Modify for Your Use Case\n\n```\n# Update configuration values\norchestrator.server.workers = 8 # More workers\norchestrator.queue.max_concurrent_tasks = 20 # Higher concurrency\n```\n\n### 3. Validate Configuration\n\n```\nnickel typecheck examples/orchestrator-custom.ncl\nnickel eval examples/orchestrator-custom.ncl\n```\n\n### 4. Document Purpose\nAdd comments explaining:\n- Use case (deployment scenario)\n- Resource requirements\n- Expected load\n- Customization needed\n\n### 5. Save as Reference\n\n```\nmv examples/orchestrator-custom.ncl examples/orchestrator-{scenario}.ncl\n```\n\n## Best Practices for Examples\n\n1. **Clear documentation** - Explain the use case at the top\n2. **Realistic values** - Use production-appropriate configurations\n3. **Complete configuration** - Include all required sections\n4. **Inline comments** - Explain non-obvious choices\n5. **Validated** - Typecheck all examples before committing\n6. **Organized** - Group by service and deployment mode\n\n## Example Naming Convention\n\n- **Service-mode**: `{service}-{mode}.ncl` (orchestrator-solo.ncl)\n- **Scenario**: `{service}-{scenario}.ncl` (orchestrator-gpu-intensive.ncl)\n- **Full stack**: `full-platform-{mode}.ncl` (full-platform-enterprise.ncl)\n\n## Customizing Examples\n\n### For Your Environment\n\n```\n# orchestrator-solo.ncl (customized)\n{\n orchestrator = {\n workspace = {\n name = "my-workspace", # Your workspace name\n path = "/home/user/projects/workspace", # Your path\n },\n server = {\n host = "127.0.0.1", # Keep local for solo\n port = 9090,\n },\n storage = {\n backend = 'filesystem, # No external DB needed\n path = "/home/user/provisioning/data", # Your path\n },\n },\n}\n```\n\n### For Different Resources\n\n```\n# orchestrator-multiuser.ncl (customized for team)\n{\n orchestrator = {\n server = {\n host = "0.0.0.0", # Public binding\n port = 9090,\n workers = 4, # Team concurrency\n },\n queue = {\n max_concurrent_tasks = 10, # Team workload\n },\n },\n}\n```\n\n## Testing Examples\n\n```\n# Typecheck example\nnickel typecheck examples/orchestrator-solo.ncl\n\n# Evaluate and view\nnickel eval examples/orchestrator-solo.ncl | head -20\n\n# Export to TOML\nnickel export --format toml examples/orchestrator-solo.ncl > test.toml\n```\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05
|