prvng_platform/config/examples/README.md

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{$detected_lang}\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{$detected_lang}\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{$detected_lang}\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{$detected_lang}\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\nInfrastructure Examples:\n- provisioning/schemas/infrastructure/examples-solo-deployment.ncl - Solo infrastructure\n- provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl - Enterprise infrastructure\n\nWhat Gets Generated:\n\n{$detected_lang}\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\nIntegration Pattern:\n\n{$detected_lang}\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\nGenerate all infrastructure configs:\n\n{$detected_lang}\nprovisioning/platform/scripts/generate-infrastructure-configs.nu --mode solo --format yaml\nprovisioning/platform/scripts/generate-infrastructure-configs.nu --mode enterprise --format json\n\n\nValidate generated configs:\n\n{$detected_lang}\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\nInteractive setup:\n\n{$detected_lang}\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{$detected_lang}\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{$detected_lang}\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\nPlatform 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\nInfrastructure 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\nWhy Both?:\n- Platform config: How should Orchestrator behave? (internal settings)\n- Infrastructure config: How should Orchestrator be deployed? (external deployment)\n\n---\n\nLast Updated: 2025-01-06 (Updated with Infrastructure Integration Guide)\nConfigLoader Version: 2.0.0\nNickel Version: Latest\nInfrastructure Integration: Complete with schemas, examples, and validation scripts