1 line
8.0 KiB
Markdown
1 line
8.0 KiB
Markdown
# 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 |