prvng_platform/installer/docs/CONFIG_QUICK_REFERENCE.md

# Installer Configuration - Quick Reference

## Quick Start

### Load Configuration
```rust
use provisioning_installer::config::*;

// Auto-discover config file
let config = load_default_config()?;

// From specific file
let config = load_config_from_file("config.toml")?;

// With CLI overrides
let config = load_config_with_cli(cli_config)?;
```

### Validate Configuration
```rust
// Validate file
let result = validate_config_file("config.toml")?;
if !result.is_valid {
    result.print();
}

// Validate config object
let validator = ConfigValidator::new(config);
let result = validator.validate();
```

### Create Configuration
```rust
// Minimal config
let config = create_minimal_config(
    Some("docker"),
    "solo",
    "localhost"
);

// Full builder
let config = ConfigBuilder::new()
    .with_config_file("config.toml")
    .with_cli_config(cli)
    .build()?;
```

## Configuration Priority

**Order** (highest to lowest):
1. CLI arguments
2. Environment variables
3. Config file
4. Defaults

## Environment Variables

All prefixed with `PROVISIONING_INSTALLER_`:

```bash
# Installer
MODE=headless|interactive|config-driven
VERBOSE=true|false
TIMEOUT=1800

# Deployment
PLATFORM=docker|podman|kubernetes|orbstack
DEPLOYMENT_MODE=solo|multi-user|cicd|enterprise
DOMAIN=localhost
LOCATION=local|remote

# Remote
REMOTE_HOST=user@host:port
REMOTE_SSH_KEY=/path/to/key

# Resources
MIN_CPU_CORES=2
MIN_MEMORY_GB=4.0
MIN_DISK_GB=20.0

# Secrets
AUTO_GENERATE_SECRETS=true|false
SECRETS_BACKEND=file|env|kms
SECRETS_PATH=/var/lib/provisioning/secrets

# MCP
MCP_ENABLED=true|false
MCP_MODE=stdio|http|sse
MCP_ENDPOINT=http://localhost:8084

# Unattended
UNATTENDED=true|false
NOTIFICATION_EMAIL=admin@example.com

# Logging
LOG_LEVEL=debug|info|warn|error
LOG_FORMAT=json|text
```

## Config File Locations

Searched in order:
1. `./installer-config.toml`
2. `./config/installer-config.toml`
3. `/etc/provisioning/installer-config.toml`
4. `~/.config/provisioning/installer-config.toml`

## Deployment Modes

| Mode | CPU | RAM | Services | Use Case |
|------|-----|-----|----------|----------|
| **solo** | 2 | 4GB | 3-5 | Local development |
| **multi-user** | 4 | 8GB | 7+ | Team collaboration |
| **cicd** | 8 | 16GB | 8-10 | Automation pipelines |
| **enterprise** | 16 | 32GB | 15+ | Production deployment |

## Core Services

**Always Required**:
- `orchestrator` (8080) - Task coordination
- `control_center` (8081) - Web UI
- `coredns` (5353) - DNS service

**Mode-Specific**:
- **Multi-User+**: gitea, postgres
- **CI/CD+**: oci_registry
- **Enterprise**: harbor, prometheus, grafana, loki, kms, nginx

## Example Configs

### Solo Developer
```toml
[deployment]
mode = "solo"
platform = "docker"
domain = "localhost"

[services.orchestrator]
enabled = true
[services.control_center]
enabled = true
```

### Multi-User Team
```toml
[deployment]
mode = "multi-user"
platform = "docker"

[services.gitea]
enabled = true
[services.postgres]
enabled = true
```

### Enterprise
```toml
[deployment]
mode = "enterprise"
platform = "kubernetes"

[services.harbor]
enabled = true
[services.prometheus]
enabled = true
[services.kms]
enabled = true
```

## Validation Rules

**Errors** (block deployment):
- Invalid platform/mode
- Missing required services
- Port conflicts (enabled services)
- Invalid resource formats
- Missing remote config

**Warnings** (advisory):
- Resources below recommended
- Platform-mode mismatches
- Dual registry enabled
- Secrets in config

## API Reference

### Types
```rust
Config                  // Main config
InstallerConfig        // Installer settings
DeploymentConfig       // Deployment settings
ServicesConfig         // Service configs
SecretsConfig          // Secrets management
MCPConfig              // MCP settings
UnattendedConfig       // Automation
```

### Functions
```rust
load_default_config() -> Result<Config>
load_config_from_file(path) -> Result<Config>
load_config_with_cli(cli) -> Result<Config>
validate_config_file(path) -> Result<ValidationResult>
create_minimal_config(platform, mode, domain) -> Config
```

### Builder
```rust
ConfigBuilder::new()
    .with_config_file(path)
    .with_cli_config(config)
    .with_env_prefix(prefix)
    .skip_mode_defaults()
    .skip_conflict_resolution()
    .skip_validation()
    .build() -> Result<Config>
```

## Common Tasks

### Validate Config
```bash
# Via CLI
provisioning-installer validate --config config.toml

# Programmatic
let result = validate_config_file("config.toml")?;
result.print();
```

### Override Platform
```rust
let mut cli = Config::default();
cli.deployment.platform = Some("podman".to_string());
let config = load_config_with_cli(cli)?;
```

### Set Resources
```toml
[resources]
min_cpu_cores = 8
min_memory_gb = 16.0
allocation_strategy = "recommended"
```

### Enable Service
```toml
[services.mcp_server]
enabled = true
port = 8084
cpu_limit = "1000m"
memory_limit = "512Mi"
```

### Remote Deployment
```toml
[deployment]
location = "remote"

[deployment.remote]
host = "user@server:22"
ssh_key = "~/.ssh/deploy_key"
install_path = "/opt/provisioning"
```

## Conflict Resolution

**Automatic**:
- Harbor vs Zot: Mode-dependent
- MCP server: Follows MCP config
- KMS: Enabled if secrets backend = "kms"
- Remote config: Cleared if location = "local"

## Testing

```bash
# Run all tests
cargo test --lib

# Specific test
cargo test config::validator::tests::test_valid_config

# With output
cargo test -- --nocapture
```

## Troubleshooting

**Config not found**:
- Check search paths
- Use absolute path
- Set via environment

**Validation fails**:
- Run with `--verbose`
- Check error messages
- Verify service dependencies

**Port conflicts**:
- Only enabled services checked
- Change ports in config
- Disable conflicting service

**Resource warnings**:
- Increase resources
- Use `skip_resource_check = true`
- Change allocation strategy

## Files

**Template**: `provisioning/config/installer-config.toml.template`
**Examples**: `provisioning/config/installer-examples/`
- `solo.toml`
- `multi-user.toml`
- `cicd.toml`
- `enterprise.toml`

**Code**: `src/config/`
- `mod.rs` - Main module
- `schema.rs` - Types
- `loader.rs` - Loading
- `validator.rs` - Validation
- `merger.rs` - Merging

**Docs**:
- `CONFIG_SYSTEM_SUMMARY.md` - Detailed overview
- `IMPLEMENTATION_REPORT.md` - Implementation details
- `CONFIG_QUICK_REFERENCE.md` - This file