provisioning/docs/src/setup/initial-setup.md

Initial Setup

Configure Provisioning after installation.

Overview

Initial setup validates your environment and prepares Provisioning for workspace creation. The setup process performs system detection, dependency verification, and configuration initialization.

Prerequisites

Before initial setup, ensure:

1. Provisioning CLI installed and in PATH
2. Nushell 0.109.0+ installed
3. Nickel installed
4. SOPS 3.10.2+ installed
5. Age 1.2.1+ installed
6. K9s 0.50.6+ installed (for Kubernetes)

Verify installation:

provisioning version
nu --version
nickel --version
sops --version
age --version

Setup Profiles

Provisioning provides configuration profiles for different use cases:

1. Developer Profile

For local development and testing:

provisioning setup profile --profile developer

Includes:

• Local provider (simulation environment)
• Development workspace
• Test environment configuration
• Debug logging enabled
• No MFA required
• Workspace directory: ~/.provisioning-dev/

2. Production Profile

For production deployments:

provisioning setup profile --profile production

Includes:

• Encrypted configuration
• Strict validation rules
• MFA enabled
• Audit logging enabled
• Workspace directory: /opt/provisioning/

3. CI/CD Profile

For unattended automation:

provisioning setup profile --profile cicd

Includes:

• Headless mode (no TUI prompts)
• Service account authentication
• Automated backups
• Policy enforcement
• Unattended upgrade support

Configuration Detection

The setup system automatically detects:

# System detection
OS:            $(uname -s)
CPU:           $(lscpu | grep 'CPU(s)' | awk '{print $NF}')
RAM:           $(free -h | grep Mem | awk '{print $2}')
Architecture:  $(uname -m)

The system adapts configuration based on detected resources:

Detected Resource	Configuration
2-4 CPU cores	Solo (single-instance) mode
4-8 CPU cores	MultiUser mode (small cluster)
8+ CPU cores	CICD or Enterprise mode
4GB RAM	Minimal services only
8GB RAM	Standard setup
16GB+ RAM	Full feature set

Setup Steps

Step 1: Validate Environment

provisioning setup validate

Checks:

• ✅ All dependencies installed
• ✅ Permission levels
• ✅ Network connectivity
• ✅ Disk space (minimum 20GB recommended)

Step 2: Initialize Configuration

provisioning setup init

Creates:

• ~/.config/provisioning/ - User configuration directory
• ~/.config/provisioning/user_config.yaml - User settings
• ~/.provisioning/workspaces/ - Workspace registry

Step 3: Configure Providers

provisioning setup providers

Interactive configuration for:

• UpCloud (API key, endpoint)
• AWS (Access key, secret, region)
• Hetzner (API token)
• Local (No configuration required)

Store credentials securely:

# Credentials are encrypted with SOPS + Age
~/.config/provisioning/.secrets/providers.enc.yaml

Step 4: Configure Security

provisioning setup security

Sets up:

• JWT secret for authentication
• KMS backend (local, Cosmian, AWS KMS)
• Encryption keys
• Certificate authorities

Step 5: Verify Installation

provisioning verify

Checks:

• ✅ All components running
• ✅ Provider connectivity
• ✅ Configuration validity
• ✅ Security systems operational

User Configuration

User configuration is stored in ~/.config/provisioning/user_config.yaml:

# User preferences
user:
  name: "Your Name"
  email: "[your@email.com](mailto:your@email.com)"
  default_region: "us-east-1"

# Workspace settings
workspaces:
  active: "my-project"
  directory: "~/.provisioning/workspaces/"
  registry:
    my-project:
      path: "/home/user/.provisioning/workspaces/workspace_my_project"
      created: "2026-01-16T10:30:00Z"
      template: "default"

# Provider defaults
providers:
  default: "upcloud"
  upcloud:
    endpoint: " [https://api.upcloud.com"](https://api.upcloud.com")
  aws:
    region: "us-east-1"

# Security settings
security:
  mfa_enabled: false
  kms_backend: "local"
  encryption: "aes-256-gcm"

# Display options
ui:
  theme: "dark"
  table_format: "compact"
  colors: true

# Logging
logging:
  level: "info"
  output: "console"
  file: "~/.provisioning/logs/provisioning.log"

Environment Variables

Override settings with environment variables:

# Provider selection
export PROVISIONING_PROVIDER=aws

# Workspace selection
export PROVISIONING_WORKSPACE=my-project

# Logging
export PROVISIONING_LOG_LEVEL=debug

# Configuration path
export PROVISIONING_CONFIG=~/.config/provisioning/

# KMS endpoint
export PROVISIONING_KMS_ENDPOINT= [http://localhost:8080](http://localhost:8080)

Troubleshooting

Missing Dependencies

# Install missing tools
brew install nushell nickel sops age k9s

# Verify
provisioning setup validate

Permission Errors

# Fix directory permissions
chmod 700 ~/.config/provisioning/
chmod 600 ~/.config/provisioning/user_config.yaml

Provider Connection Failed

# Test provider connectivity
provisioning providers test upcloud --verbose

# Verify credentials
cat ~/.config/provisioning/.secrets/providers.enc.yaml

Next Steps

After initial setup:

1. Create workspace
2. Configure infrastructure
3. Deploy first cluster