provisioning/docs/src/setup

Setup & Configuration

Post-installation configuration and system setup for the Provisioning platform.

Overview

After installation, setup configures your system and prepares workspaces for infrastructure deployment.

Setup encompasses three critical phases:

1. Initial Setup - Environment detection, dependency verification, directory creation
2. Workspace Setup - Create workspaces, configure providers, initialize schemas
3. Configuration - Provider credentials, system settings, profiles, validation

This process validates prerequisites, detects your environment, and bootstraps your first workspace.

Quick Setup

Get up and running in 3 commands:

# 1. Complete initial setup (detects system, creates dirs, validates dependencies)
provisioning setup initial

# 2. Create first workspace (for your infrastructure)
provisioning workspace create --name production

# 3. Add cloud provider credentials (AWS, UpCloud, Hetzner, etc.)
provisioning config set --workspace production \
  extensions.providers.aws.enabled true \
  extensions.providers.aws.config.region us-east-1

# 4. Verify configuration is valid
provisioning validate config

Setup Process Explained

The setup system automatically:

1. System Detection - Detects OS (Linux, macOS, Windows), CPU architecture, RAM, disk space
2. Dependency Verification - Validates Nushell, Nickel, SOPS, Age, K9s installation
3. Directory Structure - Creates ~/.provisioning/, ~/.config/provisioning/, workspace directories
4. Configuration Creation - Initializes default configuration, security settings, profiles
5. Workspace Bootstrap - Creates default workspace with basic configuration
6. Health Checks - Validates installation, runs diagnostic tests

All steps are logged and can be verified with provisioning status.

Setup Configuration Guides

Starting Fresh

• Initial Setup - First-time system setup: detection, validation, directory creation, default configuration, health checks.

• Workspace Setup - Create and initialize workspaces: creation, provider configuration, schema management, local customization.

• Configuration Management - Configure system: providers, credentials, profiles, environment variables, validation rules.

Setup Profiles

Pre-configured setup profiles for different use cases:

Developer Profile

provisioning setup profile --profile developer
# Configures for local development with demo provider

Production Profile

provisioning setup profile --profile production
# Configures for production with security hardening

Custom Profile

provisioning setup profile --custom
# Interactive setup with customization

Directory Structure Created

Setup creates this directory structure:

~/.provisioning/
├── workspaces/           # Workspace data
├── cache/                # Build and dependency cache
├── plugins/              # Installed Nushell plugins
└── detectors/            # Custom detectors

~/.config/provisioning/
├── config.toml          # Main configuration
├── providers/           # Provider credentials
├── secrets/             # Encrypted secrets (via SOPS)
└── profiles/            # Setup profiles

Quick Setup Verification

# Check system status
provisioning status

# Verify all dependencies
provisioning setup verify-dependencies

# Test cloud provider connection
provisioning provider test --name aws

# Validate configuration
provisioning validate config

# Run health checks
provisioning health check

Environment-Specific Setup

For Single Workspace (Simple)

1. Run Initial Setup
2. Create one workspace
3. Configure provider
4. Done!

For Multiple Workspaces (Team)

1. Run Initial Setup
2. Create multiple workspaces per team
3. Configure shared providers
4. Set up workspace-specific schemas

For Multi-Cloud (Enterprise)

1. Run Initial Setup with production profile
2. Create workspace per environment (dev, staging, prod)
3. Configure multiple cloud providers
4. Enable audit logging and security features

Configuration Hierarchy

Configurations load in priority order:

1. Command-line arguments       (highest)
2. Environment variables        (PROVISIONING_*)
3. User profile config         (~/.config/provisioning/)
4. Workspace config            (workspace/config/)
5. System defaults             (provisioning/config/)
                               (lowest)

Common Setup Tasks

Add a Cloud Provider

provisioning config set --workspace production \
  extensions.providers.aws.config.region us-east-1 \
  extensions.providers.aws.config.credentials_source aws_iam

Configure Secrets Storage

provisioning config set \
  security.secrets.backend secretumvault \
  security.secrets.url  [http://localhost:8200](http://localhost:8200)

Enable Audit Logging

provisioning config set \
  security.audit.enabled true \
  security.audit.retention_days 2555

Set Up Multi-Tenancy

# Create separate workspaces per tenant
provisioning workspace create --name tenant-1
provisioning workspace create --name tenant-2

# Each workspace has isolated configuration

Setup Validation

After setup, validate everything works:

# Run complete validation suite
provisioning setup validate-all

# Or check specific components
provisioning setup validate-system       # OS, dependencies
provisioning setup validate-directories  # Directory structure
provisioning setup validate-config       # Configuration syntax
provisioning setup validate-providers    # Cloud provider connectivity
provisioning setup validate-security     # Security settings

Troubleshooting Setup

If setup fails:

1. Check logs - provisioning setup logs --tail 20
2. Verify dependencies - provisioning setup verify-dependencies
3. Reset configuration - provisioning setup reset --workspace <name>
4. Run diagnostics - provisioning diagnose setup
5. Check documentation - See Troubleshooting

Next Steps After Setup

After initial setup completes:

1. Create workspaces - See Workspace Setup
2. Configure providers - See Configuration Management
3. Deploy infrastructure - See Getting Started
4. Learn features - See Features
5. Explore examples - See Examples

Related Documentation

• Getting Started → See provisioning/docs/src/getting-started/
• Features → See provisioning/docs/src/features/
• Configuration Guide → See provisioning/docs/src/infrastructure/
• Troubleshooting → See provisioning/docs/src/troubleshooting/