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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
# 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

```bash
provisioning setup validate
```

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

### Step 2: Initialize Configuration

```bash
provisioning setup init
```

Creates:
- `~/.config/provisioning/` - User configuration directory
- `~/.config/provisioning/user_config.yaml` - User settings
- `~/.provisioning/workspaces/` - Workspace registry

### Step 3: Configure Providers

```bash
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:

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

### Step 4: Configure Security

```bash
provisioning setup security
```

Sets up:
- JWT secret for authentication
- KMS backend (local, Cosmian, AWS KMS)
- Encryption keys
- Certificate authorities

### Step 5: Verify Installation

```bash
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`:

```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:

```bash
# 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

```bash
# Install missing tools
brew install nushell nickel sops age k9s

# Verify
provisioning setup validate
```

### Permission Errors

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

### Provider Connection Failed

```bash
# 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](workspace-setup.md)
2. [Configure infrastructure](configuration.md)
3. [Deploy first cluster](../guides/from-scratch.md)