provisioning/schemas/platform/defaults/README.md

Defaults

Default configuration values for all services and deployment modes.

Purpose

Defaults provide:

• Base values for all configuration fields
• Mode-specific overrides (solo, multiuser, cicd, enterprise)
• Composition with validators for constraint checking
• Documentation of recommended values

File Organization

defaults/
├── README.md                           # This file
├── common/                             # Shared defaults
│   ├── server-defaults.ncl             # HTTP server defaults
│   ├── database-defaults.ncl           # Database defaults
│   ├── security-defaults.ncl           # Security defaults
│   ├── monitoring-defaults.ncl         # Monitoring defaults
│   └── logging-defaults.ncl            # Logging defaults
├── deployment/                         # Mode-specific defaults
│   ├── solo-defaults.ncl               # Solo mode (2 CPU, 4GB)
│   ├── multiuser-defaults.ncl          # Multi-user mode (4 CPU, 8GB)
│   ├── cicd-defaults.ncl               # CI/CD mode (8 CPU, 16GB)
│   └── enterprise-defaults.ncl         # Enterprise mode (16+ CPU, 32+ GB)
├── orchestrator-defaults.ncl           # Orchestrator base defaults
├── control-center-defaults.ncl         # Control Center base defaults
├── mcp-server-defaults.ncl             # MCP Server base defaults
└── installer-defaults.ncl              # Installer base defaults

Composition Pattern

Configuration is built from layers:

Base Defaults (service-defaults.ncl)
    ↓
+ Mode Overlay (deployment/{mode}-defaults.ncl)
    ↓
+ User Customization (values/{service}.{mode}.ncl)
    ↓
+ Schema Validation (schemas/*.ncl)
    ↓
= Final Configuration (configs/{service}.{mode}.ncl)

Example:

# configs/orchestrator.solo.ncl
let defaults = import "../defaults/orchestrator-defaults.ncl" in
let solo_defaults = import "../defaults/deployment/solo-defaults.ncl" in

{
  orchestrator = defaults.orchestrator & {
    # Mode-specific overrides
    server.workers = 2,          # Solo mode: fewer workers
    queue.max_concurrent_tasks = 3,  # Solo: limited concurrency
  },
}

Default Value Hierarchy

1. Service Base Defaults

orchestrator-defaults.ncl:

{
  orchestrator = {
    workspace = {
      name = "default",
      path = "/var/lib/provisioning/orchestrator",
      enabled = true,
      multi_workspace = false,
    },
    server = {
      host = "127.0.0.1",
      port = 9090,
      workers = 4,        # General default
    },
    storage = {
      backend = 'filesystem,
      path = "/var/lib/provisioning/orchestrator/data",
    },
    queue = {
      max_concurrent_tasks = 5,
      retry_attempts = 3,
    },
  },
}

2. Mode-Specific Overrides

deployment/solo-defaults.ncl:

{
  resources = {
    cpu_cores = 2,
    memory_mb = 4096,
  },
  services = {
    orchestrator = {
      workers = 2,                    # Override: fewer workers for solo
      queue_max_concurrent_tasks = 3,  # Override: limited concurrency
      storage_backend = 'filesystem,
    },
  },
}

deployment/enterprise-defaults.ncl:

{
  resources = {
    cpu_cores = 16,
    memory_mb = 32768,
  },
  services = {
    orchestrator = {
      workers = 16,                   # Override: more workers for enterprise
      queue_max_concurrent_tasks = 50,  # Override: high concurrency
      storage_backend = 'surrealdb_server,
      surrealdb_url = "surrealdb://cluster:8000",
    },
  },
}

Common Defaults

server-defaults.ncl

{
  server = {
    host = "0.0.0.0",        # Accept all interfaces
    port = 8080,             # Standard HTTP port (service-specific override)
    workers = 4,             # CPU-aware default
    keep_alive = 75,         # seconds
    max_connections = 100,
  },
}

database-defaults.ncl

{
  database = {
    backend = 'rocksdb,      # Fast embedded default
    path = "/var/lib/provisioning/data",
    pool_size = 10,          # Connection pool
    timeout = 30000,         # milliseconds
  },
}

security-defaults.ncl

{
  security = {
    jwt_issuer = "provisioning-system",
    jwt_expiration = 3600,   # 1 hour
    encryption_key = "",     # User must set
    kms_backend = "age",     # Local encryption
    mfa_required = false,    # Solo: disabled by default
  },
}

monitoring-defaults.ncl

{
  monitoring = {
    enabled = false,         # Optional feature
    metrics_interval = 60,   # seconds
    health_check_interval = 30,
    retention_days = 30,
  },
}

Mode Configurations

Solo Mode

• Use case: Single developer, testing
• Resources: 2 CPU, 4GB RAM, 50GB disk
• Database: Filesystem or embedded (RocksDB)
• Security: Simplified (no MFA, local encryption)
• Services: Core services only (orchestrator, control-center)

MultiUser Mode

• Use case: Team collaboration, staging
• Resources: 4 CPU, 8GB RAM, 100GB disk
• Database: PostgreSQL or SurrealDB server
• Security: RBAC enabled, shared authentication
• Services: Full platform (orchestrator, control-center, MCP, Gitea)

CI/CD Mode

• Use case: Automated pipelines, testing
• Resources: 8 CPU, 16GB RAM, 200GB disk
• Database: Ephemeral, fast cleanup
• Security: API tokens, no UI
• Services: Minimal (orchestrator in API mode)

Enterprise Mode

• Use case: Production, high availability
• Resources: 16+ CPU, 32+ GB RAM, 500GB+ disk
• Database: SurrealDB cluster with replication
• Security: MFA required, KMS integration, compliance
• Services: Full platform with redundancy, monitoring, logging

Modifying Defaults

Changing a Base Default

orchestrator-defaults.ncl:

# Before
queue = {
  max_concurrent_tasks = 5,
},

# After
queue = {
  max_concurrent_tasks = 10,  # Increased default
},

Then:

1. Test with: nickel eval configs/orchestrator.solo.ncl
2. Verify forms still work
3. Update documentation if default meaning changes

Changing Mode Override

deployment/solo-defaults.ncl:

# Before
orchestrator = {
  workers = 2,
}

# After
orchestrator = {
  workers = 1,  # Reduce to 1 for solo
}

Best Practices

1. Keep it conservative - Default to safe, minimal values
2. Document overrides - Explain why mode-specific values differ
3. Use composition - Import and merge rather than duplicate
4. Test composition - Verify defaults merge correctly with modes
5. Provide examples - Use examples/ directory to show realistic setups

Testing Defaults

# Evaluate defaults
nickel eval provisioning/.typedialog/provisioning/platform/defaults/orchestrator-defaults.ncl

# Test merged defaults (base + mode)
nickel eval provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl | head -50

# Typecheck with schemas
nickel typecheck provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl

Default Value Guidelines

Ports

• Solo mode: Local (127.0.0.1) only
• Multi-user/Enterprise: Bind all interfaces (0.0.0.0)
• Never conflict with system services

Workers/Concurrency

• Solo: 1-2 workers, limited concurrency
• Multi-user: 4-8 workers, moderate concurrency
• Enterprise: 8+ workers, high concurrency

Resources

• Solo: 2 CPU, 4GB RAM (laptop testing)
• Multi-user: 4 CPU, 8GB RAM (team servers)
• Enterprise: 16+ CPU, 32+ GB RAM (production)

Security

• Solo: Disabled/minimal (local development)
• Multi-user: RBAC enabled (shared team)
• Enterprise: MFA required, KMS backend (production)

Storage

• Solo: Filesystem or RocksDB (no infrastructure needed)
• Multi-user: PostgreSQL or SurrealDB (team data)
• Enterprise: SurrealDB cluster with replication (HA)

---

Version: 1.0.0 Last Updated: 2025-01-05