28 KiB
28 KiB
\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\nDeployment Mode: Solo (Single Developer)\n\nResource Requirements:\n- CPU: 2 cores\n- RAM: 4 GB\n- Disk: 50 GB (local data)\n\nConfiguration 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\nIdeal 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\nKey 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\nKey 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\nUsage:\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\nCustomization 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\nDeployment Mode: Enterprise (Production High-Availability)\n\nResource Requirements:\n- CPU: 8+ cores (recommended 16)\n- RAM: 16+ GB (recommended 32+ GB)\n- Disk: 500+ GB (SurrealDB cluster)\n\nConfiguration 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\nIdeal 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\nKey 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\nKey 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\nEnvironment Variables Required:\n\n\nexport JWT_SECRET="<secure-random-256-bit-string>"\nexport SURREALDB_PASSWORD="<database-password>"\n\n\nUsage:\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\nCustomization 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\nDeployment Mode: MultiUser (Team Collaboration & Staging)\n\nResource Requirements:\n- CPU: 4 cores\n- RAM: 8 GB\n- Disk: 100 GB (PostgreSQL data + logs)\n\nConfiguration 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\nIdeal 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\nKey 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\nKey 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\nEnvironment Variables Required:\n\n\nexport DB_PASSWORD="<postgresql-password>"\nexport JWT_SECRET="<secure-random-string>"\n\n\nUsage:\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\nRBAC 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\nCustomization 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\nDeployment Mode: Enterprise Integrated (Complete Platform)\n\nResource 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\nServices Configured:\n\nOrchestrator 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\nControl 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\nMCP 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\nGlobal Configuration:\n\n\nlet deployment_mode = "enterprise"\nlet namespace = "provisioning"\nlet domain = "provisioning.example.com"\nlet environment = "production"\n\n\nInfrastructure 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\nIdeal 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\nKey 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\nKey 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\nEnvironment 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\nArchitecture 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\nUsage:\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\nCustomization 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\nCause: Field value doesn't match expected type\n\nFix: 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\nFix: Change the port in your configuration:\n\n\nserver.port = 9999 # Instead of 9090\n\n\n### Database Connection Errors\n\nFix: 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\nFix: 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\nVersion: 2.0\nLast Updated: 2025-01-05\nStatus: 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\nVersion: 1.0.0\nLast Updated: 2025-01-05