provisioning/docs/src/infrastructure/configuration-system.md

# Configuration System

The Provisioning platform uses a hierarchical configuration system with Nickel as the source of
truth for infrastructure definitions and TOML/YAML for application settings.

## Configuration Hierarchy

Configuration is loaded in order of precedence (highest to lowest):

```plaintext
1. Runtime Arguments    - CLI flags (--config, --workspace, etc.)
2. Environment Variables - PROVISIONING_* environment variables
3. User Configuration   - ~/.config/provisioning/user_config.yaml
4. Infrastructure Config - Nickel schemas in workspace/provisioning
5. System Defaults      - provisioning/config/config.defaults.toml
```

Later sources override earlier ones, allowing flexible configuration management across environments.

## Configuration Files

### System Defaults

Located at `provisioning/config/config.defaults.toml`:

```toml
[general]
log_level = "info"
workspace_root = "./workspaces"

[providers]
default_provider = "local"

[orchestrator]
max_parallel_tasks = 4
checkpoint_enabled = true
```

### User Configuration

Located at `~/.config/provisioning/user_config.yaml`:

```yaml
general:
  preferred_editor: nvim
  default_workspace: production

providers:
  upcloud:
    default_zone: fi-hel1
  aws:
    default_region: eu-west-1
```

### Workspace Configuration

Nickel-based infrastructure configuration in workspace directories:

```plaintext
workspace/
├── config/
│   ├── main.ncl           # Workspace configuration
│   ├── providers.ncl      # Provider definitions
│   └── variables.ncl      # Workspace variables
├── infra/
│   └── servers.ncl        # Infrastructure definitions
└── .workspace/
    └── metadata.toml      # Workspace metadata
```

## Environment Variables

All configuration can be overridden via environment variables:

```bash
export PROVISIONING_LOG_LEVEL=debug
export PROVISIONING_WORKSPACE=production
export PROVISIONING_PROVIDER=upcloud
export PROVISIONING_DRY_RUN=true
```

Variable naming: `PROVISIONING_<SECTION>_<KEY>` (uppercase with underscores).

## Configuration Accessors

The platform provides 476+ configuration accessors for programmatic access:

```nushell
# Get configuration value
provisioning config get general.log_level

# Set configuration value (workspace-scoped)
provisioning config set providers.default_provider upcloud

# List all configuration
provisioning config list

# Validate configuration
provisioning config validate
```

## Profiles

Configuration supports profiles for different environments:

```toml
[profiles.development]
log_level = "debug"
dry_run = true

[profiles.production]
log_level = "warn"
dry_run = false
checkpoint_enabled = true
```

Activate profile:

```bash
provisioning --profile production deploy
```

## Inheritance and Overrides

Workspace configurations inherit from system defaults:

```nickel
# workspace/config/main.ncl
let parent = import "../../provisioning/schemas/defaults.ncl" in
parent & {
  # Override specific values
  general.log_level = "debug",
  providers.default_provider = "aws",
}
```

## Secrets Management

Sensitive configuration is encrypted using SOPS/Age:

```bash
# Encrypt configuration
sops --encrypt --age <public-key> secrets.yaml > secrets.enc.yaml

# Decrypt and use
provisioning deploy --secrets secrets.enc.yaml
```

Integration with SecretumVault for enterprise secrets management (see [Secrets Management](../security/secrets-management.md)).

## Configuration Validation

All Nickel-based configuration is validated before use:

```bash
# Validate workspace configuration
provisioning config validate

# Check schema compliance
nickel export --format json workspace/config/main.ncl
```

Type-safety is mandatory - invalid configuration is rejected at load time.

## Best Practices

1. **Use Nickel for infrastructure** - Type-safe, validated infrastructure definitions
2. **Use TOML for application settings** - Simple key-value configuration
3. **Encrypt secrets** - Never commit unencrypted credentials
4. **Document overrides** - Comment why values differ from defaults
5. **Validate before deploy** - Always run `config validate` before deployment
6. **Version control** - Track configuration changes in Git
7. **Profile separation** - Isolate development/staging/production configs

## Troubleshooting

### Configuration Not Loading

Check precedence order:

```bash
# Show effective configuration
provisioning config show --debug

# Trace configuration loading
PROVISIONING_LOG_LEVEL=trace provisioning config list
```

### Schema Validation Failures

```bash
# Check Nickel syntax
nickel typecheck workspace/config/main.ncl

# Export and inspect
nickel export workspace/config/main.ncl
```

### Environment Variable Issues

```bash
# List all PROVISIONING_* variables
env | grep PROVISIONING_

# Clear all provisioning env vars
unset $(env | grep PROVISIONING_ | cut -d= -f1 | xargs)
```

## References

- [Nickel Guide](nickel-guide.md) - Infrastructure configuration
- [Schemas Reference](schemas-reference.md) - Schema structure
- [Secrets Management](../security/secrets-management.md) - SecretumVault integration