prvng_platform/config/examples/README.md

Platform Configuration Examples

This directory contains example Nickel files demonstrating how to generate platform configurations for different deployment modes.

File Structure

examples/
├── README.md                           # This file
├── orchestrator.solo.example.ncl        # Solo deployment (1 CPU, 1GB memory)
├── orchestrator.multiuser.example.ncl   # Multiuser deployment (2 CPU, 2GB memory, HA)
├── orchestrator.enterprise.example.ncl  # Enterprise deployment (4 CPU, 4GB memory, 3 replicas)
└── control-center.solo.example.ncl      # Control Center solo deployment

Usage

To generate actual TOML configuration from an example:

# Export to TOML (placed in runtime/generated/)
nickel export --format toml examples/orchestrator.solo.example.ncl > runtime/generated/orchestrator.solo.toml

# Export to JSON for inspection
nickel export --format json examples/orchestrator.solo.example.ncl | jq .

# Type check example
nickel typecheck examples/orchestrator.solo.example.ncl

Key Concepts

1. Schemas Reference

All examples import from the schema library:

• provisioning/schemas/platform/schemas/orchestrator.ncl
• provisioning/schemas/platform/defaults/orchestrator-defaults.ncl

2. Mode-Based Composition

Each example uses composition helpers to overlay mode-specific settings:

let helpers = import "../../schemas/platform/common/helpers.ncl" in
let defaults = import "../../schemas/platform/defaults/orchestrator-defaults.ncl" in
let mode = import "../../schemas/platform/defaults/deployment/solo-defaults.ncl" in

helpers.compose_config defaults mode {
  # User-specific overrides here
}

3. ConfigLoader Integration

Generated TOML files are automatically loaded by Rust services:

use platform_config::OrchestratorConfig;

let config = OrchestratorConfig::load().expect("Failed to load orchestrator config");
println!("Orchestrator listening on port: {}", config.server.port);

Mode Reference

Mode	CPU	Memory	Replicas	Use Case
solo	1.0	1024M	1	Development, testing
multiuser	2.0	2048M	2	Staging, small production
enterprise	4.0	4096M	3+	Large production deployments
cicd	2.0	2048M	1	CI/CD pipelines

Workflow: Platform Configuration

1. Choose deployment mode → select example file (orchestrator.solo.example.ncl, etc.)
2. Customize if needed → modify the example
3. Generate config → nickel export --format toml
4. Place in runtime/generated/ → ConfigLoader picks it up automatically
5. Service reads config → via platform-config crate

Infrastructure Generation

These platform configuration examples work together with infrastructure schemas to create complete deployments.

Complete Infrastructure Stack

Beyond platform configs, you can generate complete infrastructure from schemas:

Infrastructure Examples:

• provisioning/schemas/infrastructure/examples-solo-deployment.ncl - Solo infrastructure
• provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl - Enterprise infrastructure

What Gets Generated:

# Solo deployment infrastructure
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl

# Exports:
# - docker_compose_services (5 services)
# - nginx_config (load balancer setup)
# - prometheus_config (4 scrape jobs)
# - oci_registry_config (container registry)

Integration Pattern:

Platform Config (Orchestrator, Control Center, etc.)
    ↓ ConfigLoader reads TOML
    ↓ Services start with config

Infrastructure Config (Docker, Nginx, Prometheus, etc.)
    ↓ nickel export → YAML/JSON
    ↓ Deploy with Docker/Kubernetes/Nginx

Generation and Validation

Generate all infrastructure configs:

provisioning/platform/scripts/generate-infrastructure-configs.nu --mode solo --format yaml
provisioning/platform/scripts/generate-infrastructure-configs.nu --mode enterprise --format json

Validate generated configs:

provisioning/platform/scripts/validate-infrastructure.nu --config-dir /tmp/infra

# Output shows validation results for:
# - Docker Compose (docker-compose config --quiet)
# - Kubernetes (kubectl apply --dry-run=client)
# - Nginx (nginx -t)
# - Prometheus (promtool check config)

Interactive setup:

bash provisioning/platform/scripts/setup-with-forms.sh
# Provides TypeDialog forms or FormInquire fallback for configuration

Error Handling

If configuration fails to load:

# Validate Nickel syntax
nickel typecheck examples/orchestrator.solo.example.ncl

# Check TOML validity
cargo test --package platform-config --test validation

# Verify path resolution
provisioning validate-config --check-paths

Environment Variable Overrides

Even with TOML configs, environment variables take precedence:

export PROVISIONING_MODE=multiuser
export ORCHESTRATOR_PORT=9000
provisioning orchestrator start  # Uses env overrides

Adding New Configurations

To add a new service configuration:

1. Create service-name.mode.example.ncl in this directory
2. Import the service schema: import "../../schemas/platform/schemas/service-name.ncl"
3. Compose using helpers: helpers.compose_config defaults mode {}
4. Document in this README
5. Test with: nickel typecheck and nickel export --format json

Platform vs Infrastructure Configuration

Platform Configuration (this directory):

• Service-specific settings (port, database host, logging level)
• Loaded by ConfigLoader at service startup
• Format: TOML files in runtime/generated/
• Examples: orchestrator.solo.example.ncl, orchestrator.multiuser.example.ncl

Infrastructure Configuration (provisioning/schemas/infrastructure/):

• Deployment-specific settings (replicas, resources, networking)
• Generated and validated separately
• Formats: YAML (Docker/Kubernetes), JSON (registries), conf (Nginx)
• Examples: examples-solo-deployment.ncl, examples-enterprise-deployment.ncl

Why Both?:

• Platform config: How should Orchestrator behave? (internal settings)
• Infrastructure config: How should Orchestrator be deployed? (external deployment)

---

Last Updated: 2025-01-06 (Updated with Infrastructure Integration Guide) ConfigLoader Version: 2.0.0 Nickel Version: Latest Infrastructure Integration: Complete with schemas, examples, and validation scripts