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:

```bash
# 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:

```nickel
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:

```rust
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**:
```bash
# 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**:
```bash
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**:
```bash
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
bash provisioning/platform/scripts/setup-with-forms.sh
# Provides TypeDialog forms or FormInquire fallback for configuration
```

## Error Handling

If configuration fails to load:

```bash
# 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:

```bash
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