# Platform Configuration Examples\n\nThis directory contains example Nickel files demonstrating how to generate platform configurations for different deployment modes.\n\n## File Structure\n\n```\nexamples/\n├── README.md                           # This file\n├── orchestrator.solo.example.ncl        # Solo deployment (1 CPU, 1GB memory)\n├── orchestrator.multiuser.example.ncl   # Multiuser deployment (2 CPU, 2GB memory, HA)\n├── orchestrator.enterprise.example.ncl  # Enterprise deployment (4 CPU, 4GB memory, 3 replicas)\n└── control-center.solo.example.ncl      # Control Center solo deployment\n```\n\n## Usage\n\nTo generate actual TOML configuration from an example:\n\n```\n# Export to TOML (placed in runtime/generated/)\nnickel export --format toml examples/orchestrator.solo.example.ncl > runtime/generated/orchestrator.solo.toml\n\n# Export to JSON for inspection\nnickel export --format json examples/orchestrator.solo.example.ncl | jq .\n\n# Type check example\nnickel typecheck examples/orchestrator.solo.example.ncl\n```\n\n## Key Concepts\n\n### 1. Schemas Reference\nAll examples import from the schema library:\n- `provisioning/schemas/platform/schemas/orchestrator.ncl`\n- `provisioning/schemas/platform/defaults/orchestrator-defaults.ncl`\n\n### 2. Mode-Based Composition\nEach example uses composition helpers to overlay mode-specific settings:\n\n```\nlet helpers = import "../../schemas/platform/common/helpers.ncl" in\nlet defaults = import "../../schemas/platform/defaults/orchestrator-defaults.ncl" in\nlet mode = import "../../schemas/platform/defaults/deployment/solo-defaults.ncl" in\n\nhelpers.compose_config defaults mode {\n  # User-specific overrides here\n}\n```\n\n### 3. ConfigLoader Integration\nGenerated TOML files are automatically loaded by Rust services:\n\n```\nuse platform_config::OrchestratorConfig;\n\nlet config = OrchestratorConfig::load().expect("Failed to load orchestrator config");\nprintln!("Orchestrator listening on port: {}", config.server.port);\n```\n\n## Mode Reference\n\n| Mode | CPU | Memory | Replicas | Use Case |\n| ------ | ----- | -------- | ---------- | ---------- |\n| **solo** | 1.0 | 1024M | 1 | Development, testing |\n| **multiuser** | 2.0 | 2048M | 2 | Staging, small production |\n| **enterprise** | 4.0 | 4096M | 3+ | Large production deployments |\n| **cicd** | 2.0 | 2048M | 1 | CI/CD pipelines |\n\n## Workflow: Platform Configuration\n\n1. **Choose deployment mode** → select example file (orchestrator.solo.example.ncl, etc.)\n2. **Customize if needed** → modify the example\n3. **Generate config** → `nickel export --format toml`\n4. **Place in runtime/generated/** → ConfigLoader picks it up automatically\n5. **Service reads config** → via platform-config crate\n\n## Infrastructure Generation\n\nThese platform configuration examples work together with infrastructure schemas to create complete deployments.\n\n### Complete Infrastructure Stack\n\nBeyond platform configs, you can generate complete infrastructure from schemas:\n\n**Infrastructure Examples**:\n- `provisioning/schemas/infrastructure/examples-solo-deployment.ncl` - Solo infrastructure\n- `provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl` - Enterprise infrastructure\n\n**What Gets Generated**:\n\n```\n# Solo deployment infrastructure\nnickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl\n\n# Exports:\n# - docker_compose_services (5 services)\n# - nginx_config (load balancer setup)\n# - prometheus_config (4 scrape jobs)\n# - oci_registry_config (container registry)\n```\n\n**Integration Pattern**:\n\n```\nPlatform Config (Orchestrator, Control Center, etc.)\n    ↓ ConfigLoader reads TOML\n    ↓ Services start with config\n\nInfrastructure Config (Docker, Nginx, Prometheus, etc.)\n    ↓ nickel export → YAML/JSON\n    ↓ Deploy with Docker/Kubernetes/Nginx\n```\n\n### Generation and Validation\n\n**Generate all infrastructure configs**:\n\n```\nprovisioning/platform/scripts/generate-infrastructure-configs.nu --mode solo --format yaml\nprovisioning/platform/scripts/generate-infrastructure-configs.nu --mode enterprise --format json\n```\n\n**Validate generated configs**:\n\n```\nprovisioning/platform/scripts/validate-infrastructure.nu --config-dir /tmp/infra\n\n# Output shows validation results for:\n# - Docker Compose (docker-compose config --quiet)\n# - Kubernetes (kubectl apply --dry-run=client)\n# - Nginx (nginx -t)\n# - Prometheus (promtool check config)\n```\n\n**Interactive setup**:\n\n```\nbash provisioning/platform/scripts/setup-with-forms.sh\n# Uses TypeDialog bash wrappers (TTY-safe) or basic Nushell prompts as fallback\n```\n\n## Error Handling\n\nIf configuration fails to load:\n\n```\n# Validate Nickel syntax\nnickel typecheck examples/orchestrator.solo.example.ncl\n\n# Check TOML validity\ncargo test --package platform-config --test validation\n\n# Verify path resolution\nprovisioning validate-config --check-paths\n```\n\n## Environment Variable Overrides\n\nEven with TOML configs, environment variables take precedence:\n\n```\nexport PROVISIONING_MODE=multiuser\nexport ORCHESTRATOR_PORT=9000\nprovisioning orchestrator start  # Uses env overrides\n```\n\n## Adding New Configurations\n\nTo add a new service configuration:\n\n1. Create `service-name.mode.example.ncl` in this directory\n2. Import the service schema: `import "../../schemas/platform/schemas/service-name.ncl"`\n3. Compose using helpers: `helpers.compose_config defaults mode {}`\n4. Document in this README\n5. Test with: `nickel typecheck` and `nickel export --format json`\n\n## Platform vs Infrastructure Configuration\n\n**Platform Configuration** (this directory):\n- Service-specific settings (port, database host, logging level)\n- Loaded by ConfigLoader at service startup\n- Format: TOML files in `runtime/generated/`\n- Examples: orchestrator.solo.example.ncl, orchestrator.multiuser.example.ncl\n\n**Infrastructure Configuration** (provisioning/schemas/infrastructure/):\n- Deployment-specific settings (replicas, resources, networking)\n- Generated and validated separately\n- Formats: YAML (Docker/Kubernetes), JSON (registries), conf (Nginx)\n- Examples: examples-solo-deployment.ncl, examples-enterprise-deployment.ncl\n\n**Why Both?**:\n- Platform config: How should Orchestrator behave? (internal settings)\n- Infrastructure config: How should Orchestrator be deployed? (external deployment)\n\n---\n\n**Last Updated**: 2025-01-06 (Updated with Infrastructure Integration Guide)\n**ConfigLoader Version**: 2.0.0\n**Nickel Version**: Latest\n**Infrastructure Integration**: Complete with schemas, examples, and validation scripts