provisioning/config/examples/README.md

# Example Platform Service Configurations

This directory contains reference configurations for platform services in different deployment modes. These examples show realistic settings and best practices for each mode.

## What Are These Examples?

These are **Nickel configuration files** (.ncl format) that demonstrate how to configure the provisioning platform services. They show:

- Recommended settings for each deployment mode
- How to customize services for your environment
- Best practices for development, staging, and production
- Performance tuning for different scenarios
- Security settings appropriate to each mode

## Directory Structure

```bash
provisioning/config/examples/
├── README.md                              # This file
├── orchestrator.solo.example.ncl           # Development mode reference
├── orchestrator.multiuser.example.ncl      # Team staging reference
└── orchestrator.enterprise.example.ncl     # Production reference
```

## Deployment Modes

### Solo Mode (Development)

**File**: `orchestrator.solo.example.ncl`

**Characteristics**:
- 2 CPU, 4GB RAM (lightweight)
- Single user/developer
- Local development machine
- Minimal resource consumption
- No TLS or authentication
- In-memory storage

**When to use**:
- Local development
- Testing configurations
- Learning the platform
- CI/CD test environments

**Key Settings**:
- workers: 2
- max_concurrent_tasks: 2
- max_memory: 1GB
- tls: disabled
- auth: disabled

### Multiuser Mode (Team Staging)

**File**: `orchestrator.multiuser.example.ncl`

**Characteristics**:
- 4 CPU, 8GB RAM (moderate)
- Multiple concurrent users
- Team staging environment
- Production-like testing
- Basic TLS and token auth
- Filesystem storage with caching

**When to use**:
- Team development
- Integration testing
- Staging environment
- Pre-production validation
- Multi-user environments

**Key Settings**:
- workers: 4
- max_concurrent_tasks: 10
- max_memory: 4GB
- tls: enabled (certificates required)
- auth: token-based
- storage: filesystem with replication

### Enterprise Mode (Production)

**File**: `orchestrator.enterprise.example.ncl`

**Characteristics**:
- 16+ CPU, 32+ GB RAM (high-performance)
- Multi-team, multi-workspace
- Production mission-critical
- Full redundancy and HA
- OAuth2/Enterprise auth
- Distributed storage with replication
- Full monitoring, tracing, audit

**When to use**:
- Production deployment
- Mission-critical systems
- High-availability requirements
- Multi-tenant environments
- Compliance requirements (SOC2, ISO27001)

**Key Settings**:
- workers: 16
- max_concurrent_tasks: 100
- max_memory: 32GB
- tls: mandatory (TLS 1.3)
- auth: OAuth2 (enterprise provider)
- storage: distributed with 3-way replication
- monitoring: comprehensive with tracing
- disaster_recovery: enabled
- compliance: SOC2, ISO27001

## How to Use These Examples

### Step 1: Copy the Appropriate Example

Choose the example that matches your deployment mode:

```bash
# For development (solo)
cp provisioning/config/examples/orchestrator.solo.example.ncl 
   provisioning/config/runtime/orchestrator.solo.ncl

# For team staging (multiuser)
cp provisioning/config/examples/orchestrator.multiuser.example.ncl 
   provisioning/config/runtime/orchestrator.multiuser.ncl

# For production (enterprise)
cp provisioning/config/examples/orchestrator.enterprise.example.ncl 
   provisioning/config/runtime/orchestrator.enterprise.ncl
```

### Step 2: Customize for Your Environment

Edit the copied file to match your specific setup:

```bash
# Edit the configuration
vim provisioning/config/runtime/orchestrator.solo.ncl

# Examples of customizations:
# - Change workspace path to your project
# - Adjust worker count based on CPU cores
# - Set your domain names and hostnames
# - Configure storage paths for your filesystem
# - Update certificate paths for production
# - Set logging endpoints for your infrastructure
```

### Step 3: Validate Configuration

Verify the configuration is syntactically correct:

```toml
# Check Nickel syntax
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# View generated TOML
nickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl
```

### Step 4: Generate TOML

Export the Nickel configuration to TOML format for service consumption:

```nickel
# Use setup script to generate TOML
./provisioning/scripts/setup-platform-config.sh --generate-toml

# Or manually export
nickel export --format toml provisioning/config/runtime/orchestrator.solo.ncl > 
  provisioning/config/runtime/generated/orchestrator.solo.toml
```

### Step 5: Run Services

Start your platform services with the generated configuration:

```toml
# Set the deployment mode
export ORCHESTRATOR_MODE=solo

# Run the orchestrator
cargo run -p orchestrator
```

## Configuration Reference

### Solo Mode Example Settings

```toml
server.workers = 2
queue.max_concurrent_tasks = 2
performance.max_memory = 1000      # 1GB max
security.tls.enabled = false       # No TLS for local dev
security.auth.enabled = false      # No auth for local dev
```

**Use case**: Single developer on local machine

### Multiuser Mode Example Settings

```toml
server.workers = 4
queue.max_concurrent_tasks = 10
performance.max_memory = 4000      # 4GB max
security.tls.enabled = true        # Enable TLS
security.auth.type = "token"       # Token-based auth
```

**Use case**: Team of 5-10 developers in staging

### Enterprise Mode Example Settings

```toml
server.workers = 16
queue.max_concurrent_tasks = 100
performance.max_memory = 32000     # 32GB max
security.tls.enabled = true        # TLS 1.3 only
security.auth.type = "oauth2"      # OAuth2 for enterprise
storage.replication.factor = 3     # 3-way replication
```

**Use case**: Production with 100+ users across multiple teams

## Key Configuration Sections

### Server Configuration

Controls HTTP server behavior:

```bash
server = {
  host = "0.0.0.0",              # Bind address
  port = 9090,                   # Listen port
  workers = 4,                   # Worker threads
  max_connections = 200,         # Concurrent connections
  request_timeout = 30000,       # Milliseconds
}
```

### Storage Configuration

Controls data persistence:

```bash
storage = {
  backend = "filesystem",        # filesystem or distributed
  path = "/var/lib/provisioning/orchestrator/data",
  cache.enabled = true,
  replication.enabled = true,
  replication.factor = 3,        # 3-way replication for HA
}
```

### Queue Configuration

Controls task queuing:

```bash
queue = {
  max_concurrent_tasks = 10,
  retry_attempts = 3,
  task_timeout = 3600000,        # 1 hour in milliseconds
  priority_queue = true,         # Enable priority for tasks
  metrics = true,                # Enable queue metrics
}
```

### Security Configuration

Controls authentication and encryption:

```bash
security = {
  tls = {
    enabled = true,
    cert_path = "/etc/provisioning/certs/cert.crt",
    key_path = "/etc/provisioning/certs/key.key",
    min_tls_version = "1.3",
  },
  auth = {
    enabled = true,
    type = "oauth2",              # oauth2, token, or none
    provider = "okta",
  },
  encryption = {
    enabled = true,
    algorithm = "aes-256-gcm",
  },
}
```

### Logging Configuration

Controls log output and persistence:

```bash
logging = {
  level = "info",                # debug, info, warning, error
  format = "json",
  output = "both",               # stdout, file, or both
  file = {
    enabled = true,
    path = "/var/log/orchestrator.log",
    rotation.max_size = 104857600,  # 100MB per file
  },
}
```

### Monitoring Configuration

Controls observability and metrics:

```bash
monitoring = {
  enabled = true,
  metrics.enabled = true,
  health_check.enabled = true,
  distributed_tracing.enabled = true,
  audit_logging.enabled = true,
}
```

## Customization Examples

### Example 1: Change Workspace Name

Change the workspace identifier in solo mode:

```bash
workspace = {
  name = "myproject",
  path = "./provisioning/data/orchestrator",
}
```

Instead of default "development", use "myproject".

### Example 2: Custom Server Port

Change server port from default 9090:

```bash
server = {
  port = 8888,
}
```

Useful if port 9090 is already in use.

### Example 3: Enable TLS in Solo Mode

Add TLS certificates to solo development:

```bash
security = {
  tls = {
    enabled = true,
    cert_path = "./certs/localhost.crt",
    key_path = "./certs/localhost.key",
  },
}
```

Useful for testing TLS locally before production.

### Example 4: Custom Storage Path

Use custom storage location:

```bash
storage = {
  path = "/mnt/fast-storage/orchestrator/data",
}
```

Useful if you have fast SSD storage available.

### Example 5: Increase Workers for Staging

Increase from 4 to 8 workers in multiuser:

```bash
server = {
  workers = 8,
}
```

Useful when you have more CPU cores available.

## Troubleshooting Configuration

### Issue: "Configuration Won't Validate"

```toml
# Check for Nickel syntax errors
nickel typecheck provisioning/config/runtime/orchestrator.solo.ncl

# Get detailed error message
nickel typecheck -i provisioning/config/runtime/orchestrator.solo.ncl
```

The typecheck command will show exactly where the syntax error is.

### Issue: "Service Won't Start"

```bash
# Verify TOML was exported correctly
cat provisioning/config/runtime/generated/orchestrator.solo.toml | head -20

# Check TOML syntax is valid
toml-cli validate provisioning/config/runtime/generated/orchestrator.solo.toml
```

The TOML must be valid for the Rust service to parse it.

### Issue: "Service Uses Wrong Configuration"

```toml
# Verify deployment mode is set
echo $ORCHESTRATOR_MODE

# Check which TOML file service reads
ls -lah provisioning/config/runtime/generated/orchestrator.*.toml

# Verify TOML modification time is recent
stat provisioning/config/runtime/generated/orchestrator.solo.toml
```

The service reads from `orchestrator.{MODE}.toml` based on environment variable.

## Best Practices

### Development (Solo Mode)

1. Start simple using the solo example as-is first
2. Iterate gradually, making one change at a time
3. Enable logging by setting level = "debug" for troubleshooting
4. Disable security features for local development (TLS/auth)
5. Store data in ./provisioning/data/ which is gitignored

### Staging (Multiuser Mode)

1. Mirror production settings to test realistically
2. Enable authentication even in staging to test auth flows
3. Enable TLS with valid certificates to test secure connections
4. Set up monitoring metrics and health checks
5. Plan worker count based on expected concurrent users

### Production (Enterprise Mode)

1. Follow the enterprise example as baseline configuration
2. Use secure vault for storing credentials and secrets
3. Enable redundancy with 3-way replication for HA
4. Enable full monitoring with distributed tracing
5. Test failover scenarios regularly
6. Enable audit logging for compliance
7. Enforce TLS 1.3 and certificate rotation

## Migration Between Modes

To upgrade from solo → multiuser → enterprise:

```bash
# 1. Backup current configuration
cp provisioning/config/runtime/orchestrator.solo.ncl 
   provisioning/config/runtime/orchestrator.solo.ncl.bak

# 2. Copy new example for target mode
cp provisioning/config/examples/orchestrator.multiuser.example.ncl 
   provisioning/config/runtime/orchestrator.multiuser.ncl

# 3. Customize for your environment
vim provisioning/config/runtime/orchestrator.multiuser.ncl

# 4. Validate and generate TOML
./provisioning/scripts/setup-platform-config.sh --generate-toml

# 5. Update mode environment variable and restart
export ORCHESTRATOR_MODE=multiuser
cargo run -p orchestrator
```

## Related Documentation

- **Platform Configuration Guide**: `provisioning/docs/src/getting-started/05-platform-configuration.md`
- **Configuration README**: `provisioning/config/README.md`
- **System Status**: `provisioning/config/SETUP_STATUS.md`
- **Setup Script Reference**: `provisioning/scripts/setup-platform-config.sh.md`
- **Advanced TypeDialog Guide**: `provisioning/docs/src/development/typedialog-platform-config-guide.md`

---

**Version**: 1.0.0
**Last Updated**: 2026-01-05
**Status**: Ready to use