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

```bash
# 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](./initial-setup.md)** - First-time system setup: detection, validation, directory
  creation, default configuration, health checks.

- **[Workspace Setup](./workspace-setup.md)** - Create and initialize workspaces: creation,
  provider configuration, schema management, local customization.

- **[Configuration Management](./configuration.md)** - Configure system: providers, credentials,
  profiles, environment variables, validation rules.

## Setup Profiles

Pre-configured setup profiles for different use cases:

### Developer Profile
```bash
provisioning setup profile --profile developer
# Configures for local development with demo provider
```

### Production Profile
```bash
provisioning setup profile --profile production
# Configures for production with security hardening
```

### Custom Profile
```bash
provisioning setup profile --custom
# Interactive setup with customization
```

## Directory Structure Created

Setup creates this directory structure:

```text
~/.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

```bash
# 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](./initial-setup.md)
2. Create one workspace
3. Configure provider
4. Done!

### For Multiple Workspaces (Team)
1. Run [Initial Setup](./initial-setup.md)
2. Create multiple workspaces per team
3. Configure shared providers
4. Set up workspace-specific schemas

### For Multi-Cloud (Enterprise)
1. Run [Initial Setup](./initial-setup.md) 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:

```text
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
```bash
provisioning config set --workspace production \
  extensions.providers.aws.config.region us-east-1 \
  extensions.providers.aws.config.credentials_source aws_iam
```

### Configure Secrets Storage
```bash
provisioning config set \
  security.secrets.backend secretumvault \
  security.secrets.url  [http://localhost:8200](http://localhost:8200)
```

### Enable Audit Logging
```bash
provisioning config set \
  security.audit.enabled true \
  security.audit.retention_days 2555
```

### Set Up Multi-Tenancy
```bash
# 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:

```bash
# 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](../troubleshooting/)

## Next Steps After Setup

After initial setup completes:

1. **Create workspaces** - See [Workspace Setup](./workspace-setup.md)
2. **Configure providers** - See [Configuration Management](./configuration.md)
3. **Deploy infrastructure** - See [Getting Started](../getting-started/)
4. **Learn features** - See [Features](../features/)
5. **Explore examples** - See [Examples](../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/`
