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

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:

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

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

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

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

# Set the deployment mode
export ORCHESTRATOR_MODE=solo

# Run the orchestrator
cargo run -p orchestrator

Configuration Reference

Solo Mode Example Settings

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

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

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:

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:

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:

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:

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:

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:

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:

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

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

Example 2: Custom Server Port

Change server port from default 9090:

server = {
  port = 8888,
}

Useful if port 9090 is already in use.

Example 3: Enable TLS in Solo Mode

Add TLS certificates to solo development:

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:

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:

server = {
  workers = 8,
}

Useful when you have more CPU cores available.

Troubleshooting Configuration

Issue: "Configuration Won't Validate"

# 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"

# 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"

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

# 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