315 lines
7.8 KiB
Markdown
315 lines
7.8 KiB
Markdown
# 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
|
|
|
|
```plaintext
|
|
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:
|
|
|
|
```plaintext
|
|
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:
|
|
|
|
```nickel
|
|
# 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**:
|
|
|
|
```nickel
|
|
{
|
|
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**:
|
|
|
|
```nickel
|
|
{
|
|
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**:
|
|
|
|
```nickel
|
|
{
|
|
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
|
|
|
|
```nickel
|
|
{
|
|
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
|
|
|
|
```nickel
|
|
{
|
|
database = {
|
|
backend = 'rocksdb, # Fast embedded default
|
|
path = "/var/lib/provisioning/data",
|
|
pool_size = 10, # Connection pool
|
|
timeout = 30000, # milliseconds
|
|
},
|
|
}
|
|
```
|
|
|
|
### security-defaults.ncl
|
|
|
|
```nickel
|
|
{
|
|
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
|
|
|
|
```nickel
|
|
{
|
|
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**:
|
|
|
|
```nickel
|
|
# 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**:
|
|
|
|
```nickel
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|