# Defaults\n\nDefault configuration values for all services and deployment modes.\n\n## Purpose\n\nDefaults provide:\n- **Base values** for all configuration fields\n- **Mode-specific overrides** (solo, multiuser, cicd, enterprise)\n- **Composition with validators** for constraint checking\n- **Documentation** of recommended values\n\n## File Organization\n\n```\ndefaults/\n├── README.md                           # This file\n├── common/                             # Shared defaults\n│   ├── server-defaults.ncl             # HTTP server defaults\n│   ├── database-defaults.ncl           # Database defaults\n│   ├── security-defaults.ncl           # Security defaults\n│   ├── monitoring-defaults.ncl         # Monitoring defaults\n│   └── logging-defaults.ncl            # Logging defaults\n├── deployment/                         # Mode-specific defaults\n│   ├── solo-defaults.ncl               # Solo mode (2 CPU, 4GB)\n│   ├── multiuser-defaults.ncl          # Multi-user mode (4 CPU, 8GB)\n│   ├── cicd-defaults.ncl               # CI/CD mode (8 CPU, 16GB)\n│   └── enterprise-defaults.ncl         # Enterprise mode (16+ CPU, 32+ GB)\n├── orchestrator-defaults.ncl           # Orchestrator base defaults\n├── control-center-defaults.ncl         # Control Center base defaults\n├── mcp-server-defaults.ncl             # MCP Server base defaults\n└── installer-defaults.ncl              # Installer base defaults\n```\n\n## Composition Pattern\n\nConfiguration is built from layers:\n\n```\nBase Defaults (service-defaults.ncl)\n    ↓\n+ Mode Overlay (deployment/{mode}-defaults.ncl)\n    ↓\n+ User Customization (values/{service}.{mode}.ncl)\n    ↓\n+ Schema Validation (schemas/*.ncl)\n    ↓\n= Final Configuration (configs/{service}.{mode}.ncl)\n```\n\nExample:\n\n```\n# configs/orchestrator.solo.ncl\nlet defaults = import "../defaults/orchestrator-defaults.ncl" in\nlet solo_defaults = import "../defaults/deployment/solo-defaults.ncl" in\n\n{\n  orchestrator = defaults.orchestrator & {\n    # Mode-specific overrides\n    server.workers = 2,          # Solo mode: fewer workers\n    queue.max_concurrent_tasks = 3,  # Solo: limited concurrency\n  },\n}\n```\n\n## Default Value Hierarchy\n\n### 1. Service Base Defaults\n\n**orchestrator-defaults.ncl**:\n\n```\n{\n  orchestrator = {\n    workspace = {\n      name = "default",\n      path = "/var/lib/provisioning/orchestrator",\n      enabled = true,\n      multi_workspace = false,\n    },\n    server = {\n      host = "127.0.0.1",\n      port = 9090,\n      workers = 4,        # General default\n    },\n    storage = {\n      backend = 'filesystem,\n      path = "/var/lib/provisioning/orchestrator/data",\n    },\n    queue = {\n      max_concurrent_tasks = 5,\n      retry_attempts = 3,\n    },\n  },\n}\n```\n\n### 2. Mode-Specific Overrides\n\n**deployment/solo-defaults.ncl**:\n\n```\n{\n  resources = {\n    cpu_cores = 2,\n    memory_mb = 4096,\n  },\n  services = {\n    orchestrator = {\n      workers = 2,                    # Override: fewer workers for solo\n      queue_max_concurrent_tasks = 3,  # Override: limited concurrency\n      storage_backend = 'filesystem,\n    },\n  },\n}\n```\n\n**deployment/enterprise-defaults.ncl**:\n\n```\n{\n  resources = {\n    cpu_cores = 16,\n    memory_mb = 32768,\n  },\n  services = {\n    orchestrator = {\n      workers = 16,                   # Override: more workers for enterprise\n      queue_max_concurrent_tasks = 50,  # Override: high concurrency\n      storage_backend = 'surrealdb_server,\n      surrealdb_url = "surrealdb://cluster:8000",\n    },\n  },\n}\n```\n\n## Common Defaults\n\n### server-defaults.ncl\n\n```\n{\n  server = {\n    host = "0.0.0.0",        # Accept all interfaces\n    port = 8080,             # Standard HTTP port (service-specific override)\n    workers = 4,             # CPU-aware default\n    keep_alive = 75,         # seconds\n    max_connections = 100,\n  },\n}\n```\n\n### database-defaults.ncl\n\n```\n{\n  database = {\n    backend = 'rocksdb,      # Fast embedded default\n    path = "/var/lib/provisioning/data",\n    pool_size = 10,          # Connection pool\n    timeout = 30000,         # milliseconds\n  },\n}\n```\n\n### security-defaults.ncl\n\n```\n{\n  security = {\n    jwt_issuer = "provisioning-system",\n    jwt_expiration = 3600,   # 1 hour\n    encryption_key = "",     # User must set\n    kms_backend = "age",     # Local encryption\n    mfa_required = false,    # Solo: disabled by default\n  },\n}\n```\n\n### monitoring-defaults.ncl\n\n```\n{\n  monitoring = {\n    enabled = false,         # Optional feature\n    metrics_interval = 60,   # seconds\n    health_check_interval = 30,\n    retention_days = 30,\n  },\n}\n```\n\n## Mode Configurations\n\n### Solo Mode\n- **Use case**: Single developer, testing\n- **Resources**: 2 CPU, 4GB RAM, 50GB disk\n- **Database**: Filesystem or embedded (RocksDB)\n- **Security**: Simplified (no MFA, local encryption)\n- **Services**: Core services only (orchestrator, control-center)\n\n### MultiUser Mode\n- **Use case**: Team collaboration, staging\n- **Resources**: 4 CPU, 8GB RAM, 100GB disk\n- **Database**: PostgreSQL or SurrealDB server\n- **Security**: RBAC enabled, shared authentication\n- **Services**: Full platform (orchestrator, control-center, MCP, Gitea)\n\n### CI/CD Mode\n- **Use case**: Automated pipelines, testing\n- **Resources**: 8 CPU, 16GB RAM, 200GB disk\n- **Database**: Ephemeral, fast cleanup\n- **Security**: API tokens, no UI\n- **Services**: Minimal (orchestrator in API mode)\n\n### Enterprise Mode\n- **Use case**: Production, high availability\n- **Resources**: 16+ CPU, 32+ GB RAM, 500GB+ disk\n- **Database**: SurrealDB cluster with replication\n- **Security**: MFA required, KMS integration, compliance\n- **Services**: Full platform with redundancy, monitoring, logging\n\n## Modifying Defaults\n\n### Changing a Base Default\n\n**orchestrator-defaults.ncl**:\n\n```\n# Before\nqueue = {\n  max_concurrent_tasks = 5,\n},\n\n# After\nqueue = {\n  max_concurrent_tasks = 10,  # Increased default\n},\n```\n\n**Then**:\n1. Test with: `nickel eval configs/orchestrator.solo.ncl`\n2. Verify forms still work\n3. Update documentation if default meaning changes\n\n### Changing Mode Override\n\n**deployment/solo-defaults.ncl**:\n\n```\n# Before\norchestrator = {\n  workers = 2,\n}\n\n# After\norchestrator = {\n  workers = 1,  # Reduce to 1 for solo\n}\n```\n\n## Best Practices\n\n1. **Keep it conservative** - Default to safe, minimal values\n2. **Document overrides** - Explain why mode-specific values differ\n3. **Use composition** - Import and merge rather than duplicate\n4. **Test composition** - Verify defaults merge correctly with modes\n5. **Provide examples** - Use `examples/` directory to show realistic setups\n\n## Testing Defaults\n\n```\n# Evaluate defaults\nnickel eval provisioning/.typedialog/provisioning/platform/defaults/orchestrator-defaults.ncl\n\n# Test merged defaults (base + mode)\nnickel eval provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl | head -50\n\n# Typecheck with schemas\nnickel typecheck provisioning/.typedialog/provisioning/platform/configs/orchestrator.solo.ncl\n```\n\n## Default Value Guidelines\n\n### Ports\n- Solo mode: Local (127.0.0.1) only\n- Multi-user/Enterprise: Bind all interfaces (0.0.0.0)\n- Never conflict with system services\n\n### Workers/Concurrency\n- Solo: 1-2 workers, limited concurrency\n- Multi-user: 4-8 workers, moderate concurrency\n- Enterprise: 8+ workers, high concurrency\n\n### Resources\n- Solo: 2 CPU, 4GB RAM (laptop testing)\n- Multi-user: 4 CPU, 8GB RAM (team servers)\n- Enterprise: 16+ CPU, 32+ GB RAM (production)\n\n### Security\n- Solo: Disabled/minimal (local development)\n- Multi-user: RBAC enabled (shared team)\n- Enterprise: MFA required, KMS backend (production)\n\n### Storage\n- Solo: Filesystem or RocksDB (no infrastructure needed)\n- Multi-user: PostgreSQL or SurrealDB (team data)\n- Enterprise: SurrealDB cluster with replication (HA)\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05
