provisioning/schemas/platform/templates/configs/README.md

# Service Configuration Templates

Nickel-based configuration templates that export to TOML format for provisioning platform services.

## Overview

This directory contains Nickel templates that generate TOML configuration files for the provisioning platform services:

- **orchestrator-config.toml.ncl** - Workflow engine configuration
- **control-center-config.toml.ncl** - Policy and RBAC management configuration
- **mcp-server-config.toml.ncl** - Model Context Protocol server configuration

These templates support all four deployment modes:

- **solo**: Single developer, minimal configuration
- **multiuser**: Team collaboration with full features
- **cicd**: CI/CD pipelines with ephemeral configuration
- **enterprise**: Production with advanced security and monitoring

## Templates

### orchestrator-config.toml.ncl

Orchestrator workflow engine configuration with sections for:

- **Workspace**: Workspace name, path, and multi-workspace support
- **Server**: HTTP server configuration (host, port, workers)
- **Storage**: Backend selection (filesystem, SurrealDB embedded, SurrealDB server)
- **Queue**: Task concurrency, retries, timeouts, deadletter queue
- **Batch**: Parallel limits, operation timeouts, checkpointing, rollback
- **Monitoring**: Metrics collection, health checks, resource tracking
- **Logging**: Log levels, outputs, rotation
- **Security**: JWT auth, CORS, TLS, rate limiting
- **Extensions**: Auto-loading from OCI registry
- **Database**: Connection pooling for non-filesystem storage
- **Features**: Feature flags for experimental functionality

**Key Parameters**:
- `max_concurrent_tasks`: 1-100 (constrained)
- `batch.parallel_limit`: 1-50 (constrained)
- Storage backend: filesystem, surrealdb_server, surrealdb_cluster
- Logging format: json or text

### control-center-config.toml.ncl

Control Center policy and RBAC management configuration with sections for:

- **Server**: HTTP server configuration
- **Database**: Backend selection (RocksDB, PostgreSQL, PostgreSQL HA)
- **Auth**: JWT, OAUTH2, LDAP authentication methods
- **RBAC**: Role-based access control with roles and permissions
- **MFA**: Multi-factor authentication (TOTP, Email OTP)
- **Policies**: Password policy, session policy, audit, compliance
- **Rate Limiting**: Global and per-user rate limits
- **CORS**: Cross-origin resource sharing configuration
- **TLS**: SSL/TLS configuration
- **Monitoring**: Metrics, health checks, tracing
- **Logging**: Log outputs and rotation
- **Orchestrator Integration**: Connection to orchestrator service
- **Features**: Feature flags

**Key Parameters**:
- `database.backend`: rocksdb, postgres, postgres_ha
- `mfa.required`: false for solo/multiuser, true for enterprise
- `policies.password.min_length`: 12
- `policies.compliance`: SOC2, HIPAA support

### mcp-server-config.toml.ncl

Model Context Protocol server configuration for AI/LLM integration with sections for:

- **Server**: HTTP/Stdio protocol configuration
- **Capabilities**: Tools, resources, prompts, sampling
- **Tools**: Tool categories and configurations (orchestrator, provisioning, workspace)
- **Resources**: File system, database, external API resources
- **Prompts**: System prompts and user prompt configuration
- **Integration**: Orchestrator, Control Center, Claude API integration
- **Security**: Authentication, authorization, rate limiting, input validation
- **Monitoring**: Metrics, health checks, audit logging
- **Logging**: Log outputs and configuration
- **Features**: Feature flags
- **Performance**: Thread pools, timeouts, caching

**Key Parameters**:
- `server.protocol`: stdio (process-based) or http (network-based)
- `capabilities.tools.enabled`: true/false
- `capabilities.resources.max_size`: 1GB default
- `integration.claude.model`: claude-3-opus (latest)

## Usage

### Exporting to TOML

Each template exports to TOML format:

```toml
# Export orchestrator configuration
nickel export --format toml orchestrator-config.toml.ncl > orchestrator.toml

# Export control-center configuration
nickel export --format toml control-center-config.toml.ncl > control-center.toml

# Export MCP server configuration
nickel export --format toml mcp-server-config.toml.ncl > mcp-server.toml
```

### Mode-Specific Configuration

Override configuration values based on deployment mode using environment variables or configuration layering:

```toml
# Export solo mode configuration
ORCHESTRATOR_MODE=solo nickel export --format toml orchestrator-config.toml.ncl > orchestrator.solo.toml

# Export enterprise mode with full features
ORCHESTRATOR_MODE=enterprise nickel export --format toml orchestrator-config.toml.ncl > orchestrator.enterprise.toml
```

### Integration with Rust Services

Rust services load TOML configuration in this order (high to low priority):

1. **Environment Variables** - `ORCHESTRATOR_*`, `CONTROL_CENTER_*`, `MCP_*`
2. **User Configuration** - `~/.config/provisioning/user_config.toml`
3. **Mode-Specific Config** - `provisioning/platform/config/{service}.{mode}.toml`
4. **Default Configuration** - `provisioning/platform/config/{service}.defaults.toml`

Example loading in Rust:

```rust
use config::{Config, ConfigError, File};

pub fn load_config(mode: &str) -> Result<OrchestratorConfig, ConfigError> {
    let config_path = format!("provisioning/platform/config/orchestrator.{}.toml", mode);

    Config::builder()
        .add_source(File::with_name("provisioning/platform/config/orchestrator.defaults"))
        .add_source(File::with_name(&config_path).required(false))
        .add_source(config::Environment::with_prefix("ORCHESTRATOR"))
        .build()?
        .try_deserialize()
}
```

## Configuration Sections

### Server Configuration (All Services)

```toml
[server]
host = "0.0.0.0"
port = 9090
workers = 4
keep_alive = 75
max_connections = 512
```

### Database Configuration (Control Center)

**RocksDB** (solo, cicd modes):

```toml
[database]
backend = "rocksdb"

[database.rocksdb]
path = "/var/lib/provisioning/control-center/db"
cache_size = "256MB"
max_open_files = 1000
compression = "snappy"
```

**PostgreSQL** (multiuser, enterprise modes):

```toml
[database]
backend = "postgres"

[database.postgres]
host = "postgres.provisioning.svc.cluster.local"
port = 5432
database = "provisioning"
user = "provisioning"
password = "${DB_PASSWORD}"
ssl_mode = "require"
```

### Storage Configuration (Orchestrator)

**Filesystem** (solo, cicd modes):

```toml
[storage]
backend = "filesystem"
path = "/var/lib/provisioning/orchestrator/data"
```

**SurrealDB Server** (multiuser mode):

```toml
[storage]
backend = "surrealdb_server"
surrealdb_url = "surrealdb://surrealdb:8000"
surrealdb_namespace = "provisioning"
surrealdb_database = "orchestrator"
```

**SurrealDB Cluster** (enterprise mode):

```toml
[storage]
backend = "surrealdb_cluster"
surrealdb_url = "surrealdb://surrealdb-cluster.provisioning.svc.cluster.local:8000"
surrealdb_namespace = "provisioning"
surrealdb_database = "orchestrator"
```

### RBAC Configuration (Control Center)

```toml
[rbac]
enabled = true
default_role = "viewer"

[rbac.roles.admin]
description = "Administrator with full access"
permissions = ["*"]

[rbac.roles.operator]
description = "Operator managing orchestrator"
permissions = ["orchestrator.view", "orchestrator.execute"]
```

### Queue Configuration (Orchestrator)

```toml
[queue]
max_concurrent_tasks = 50
retry_attempts = 3
retry_delay = 5000
task_timeout = 3600000

[queue.deadletter_queue]
enabled = true
max_messages = 1000
retention_period = 86400
```

### Logging Configuration (All Services)

```toml
[logging]
level = "info"
format = "json"

[[logging.outputs]]
destination = "stdout"
level = "info"

[[logging.outputs]]
destination = "file"
path = "/var/log/provisioning/orchestrator/orchestrator.log"
level = "debug"

[logging.outputs.rotation]
max_size = "100MB"
max_backups = 10
max_age = 30
```

### Monitoring Configuration (All Services)

```toml
[monitoring]
enabled = true

[monitoring.metrics]
enabled = true
interval = 30
export_format = "prometheus"

[monitoring.health_check]
enabled = true
interval = 30
timeout = 10
```

### Security Configuration (All Services)

```toml
[security.auth]
enabled = true
method = "jwt"
jwt_secret = "${JWT_SECRET}"
jwt_issuer = "provisioning.local"
jwt_audience = "orchestrator"
token_expiration = 3600

[security.cors]
enabled = true
allowed_origins = ["https://control-center:8080"]
allowed_methods = ["GET", "POST", "PUT", "DELETE"]

[security.rate_limit]
enabled = true
requests_per_second = 1000
burst_size = 100
```

## Environment Variables

All sensitive values should be provided via environment variables:

```bash
# Secrets
export JWT_SECRET="your-jwt-secret-here"
export DB_PASSWORD="your-database-password"
export ORCHESTRATOR_TOKEN="your-orchestrator-token"
export CONTROL_CENTER_TOKEN="your-control-center-token"
export CLAUDE_API_KEY="your-claude-api-key"

# Service URLs (if different from defaults)
export ORCHESTRATOR_URL="http://orchestrator:9090"
export CONTROL_CENTER_URL="http://control-center:8080"

# Mode selection
export PROVISIONING_MODE="enterprise"
```

## Mode-Specific Overrides

### Solo Mode
- Minimal resources: 2 CPU, 4GB RAM
- Filesystem storage for orchestrator
- RocksDB for control-center
- No MFA required
- Single replica deployments
- Logging: info level

### MultiUser Mode
- Moderate resources: 4 CPU, 8GB RAM
- SurrealDB server for orchestrator
- PostgreSQL for control-center
- RBAC enabled
- 1 replica per service
- Logging: debug level

### CI/CD Mode
- Stateless configuration
- Ephemeral storage (no persistence)
- API-driven (minimal UI)
- No MFA required
- 1 replica per service
- Logging: warn level (minimal)

### Enterprise Mode
- High resources: 16+ CPU, 32+ GB RAM
- SurrealDB cluster for orchestrator HA
- PostgreSQL HA for control-center
- Full RBAC and MFA required
- 3+ replicas per service
- Full monitoring and audit logging
- Logging: info level with detailed audit

## Validation

Validate configuration before using:

```toml
# Type check with Nickel
nickel typecheck orchestrator-config.toml.ncl

# Export and validate TOML syntax
nickel export --format toml orchestrator-config.toml.ncl | toml-cli validate -
```

## References

- [Orchestrator Configuration Schema](../../schemas/orchestrator.ncl)
- [Control Center Configuration Schema](../../schemas/control-center.ncl)
- [MCP Server Configuration Schema](../../schemas/mcp-server.ncl)
- [Nickel Language](https://nickel-lang.org/)
- [TOML Format](https://toml.io/)