prvng_platform/installer/docs/CONFIG_QUICK_REFERENCE.md

Installer Configuration - Quick Reference

Quick Start

Load Configuration

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

// 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

// 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_:

# 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

[deployment]
mode = "solo"
platform = "docker"
domain = "localhost"

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

Multi-User Team

[deployment]
mode = "multi-user"
platform = "docker"

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

Enterprise

[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

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

Functions

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

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

# Via CLI
provisioning-installer validate --config config.toml

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

Override Platform

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

Set Resources

[resources]
min_cpu_cores = 8
min_memory_gb = 16.0
allocation_strategy = "recommended"

Enable Service

[services.mcp_server]
enabled = true
port = 8084
cpu_limit = "1000m"
memory_limit = "512Mi"

Remote Deployment

[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

# 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