provisioning/docs/src/getting-started/setup.md

# Unified Setup Guide

**Quick Answer**: Run `provisioning setup profile` and choose your profile.

---

## Overview

The provisioning system uses a **unified profile-based setup** that creates type-safe configurations in your platform-specific home directory. No
matter which profile you choose, all configurations are validated with Nickel before use.

### Three Setup Profiles

|  | Profile | Duration | Use Case | Deployment | Security |  |
|  | --------- | ---------- | ---------- | ----------- | ---------- |  |
|  | **Developer** | <5 min | Local development, testing, learning | Docker Compose (local) | Minimal (local defaults) |  |
|  | **Production** | ~12 min | Production-ready, HA, team deployments | Kubernetes or SSH | Full (MFA, audit, policies) |  |
|  | **CI/CD** | <2 min | Automated pipelines, ephemeral setup | Docker Compose (temp) | CI secrets |  |

All profiles use **Nickel-first architecture**: configuration source of truth is type-safe Nickel, validated before use.

---

## Quick Start (Choose Your Profile)

### Developer Profile (Recommended for First Time)

```bash
# Run unified setup
provisioning setup profile --profile developer

# What happens:
# 1. Detects your OS and system capabilities
# 2. Creates Nickel configs in platform-specific location:
#    • macOS: ~/Library/Application Support/provisioning/
#    • Linux: ~/.config/provisioning/
# 3. Validates all configs with Nickel typecheck
# 4. Starts platform services (orchestrator, control-center, KMS)
# 5. Verifies health checks

# Verify it worked
curl http://localhost:9090/health
curl http://localhost:3000/health
curl http://localhost:3001/health
```

Expected output:
```bash
╔═════════════════════════════════════════════════════╗
║   PROVISIONING SETUP - DEVELOPER PROFILE            ║
╚═════════════════════════════════════════════════════╝

✓ System detected: macOS (aarch64)
✓ Docker available: Yes
✓ Configuration location: ~/Library/Application Support/provisioning/
✓ Config validation: PASSED (Nickel typecheck)
✓ Services started: Orchestrator, Control Center, KMS
✓ Health checks: All green

Setup complete in ~4 minutes!
```

### Production Profile (HA, Security, Team Ready)

```bash
# Interactive setup for production
provisioning setup profile --profile production --interactive

# What happens:
# 1. Detects system: OS, CPU (≥4 required), memory (≥8GB recommended)
# 2. Asks for deployment mode: Kubernetes (preferred) or SSH
# 3. Asks for cloud provider: UpCloud, AWS, Hetzner, or local
# 4. Asks for security settings: MFA, audit logging, Cedar policies
# 5. Creates workspace infrastructure
# 6. Creates Nickel configs with production overlays
# 7. Validates all configs (Nickel typecheck)
# 8. Optionally starts services

# Setup with specific provider
provisioning setup profile --profile production --provider upcloud --interactive

# Verify Nickel configs validated
nickel typecheck ~/.config/provisioning/platform/deployment.ncl
```

Expected config structure:
```toml
~/.config/provisioning/
├── system.ncl                    # System detection + capabilities
├── user_preferences.ncl          # User settings (MFA, audit, etc.)
├── platform/
│   ├── deployment.ncl            # Deployment mode (kubernetes, ssh)
│   └── services.ncl              # Service endpoints and timeouts
├── providers/
│   ├── upcloud.ncl               # UpCloud config (RustyVault refs)
│   └── aws.ncl                   # AWS config (RustyVault refs)
├── workspaces/
│   └── infrastructure.ncl        # Infrastructure definitions
└── cedar-policies/
    └── default.cedar             # Authorization policies
```

### CI/CD Profile (Automated, Ephemeral)

```bash
# Fully automated setup for pipelines
export PROVISIONING_PROVIDER=local
export PROVISIONING_WORKSPACE=ci-test-${CI_JOB_ID}

provisioning setup profile --profile cicd

# What happens:
# 1. No interaction (reads from env vars)
# 2. Creates ephemeral configs in /tmp/provisioning-ci-${CI_JOB_ID}/
# 3. Validates with Nickel typecheck
# 4. Starts Docker Compose services
# 5. Registers cleanup hook (auto-cleanup on exit)

# In your CI pipeline:
# Services run, tests execute, cleanup automatic
```

---

## Configuration Locations (Platform-Aware)

### Linux (XDG Base Directory)

```bash
# Primary location
~/.config/provisioning/

# Or with XDG_CONFIG_HOME override
$XDG_CONFIG_HOME/provisioning/

# Files created during setup
~/.config/provisioning/
├── system.ncl                   # Source of truth (Nickel)
├── user_preferences.ncl         # Source of truth (Nickel)
├── platform/
│   └── deployment.ncl           # Source of truth (Nickel)
└── generated/                   # Optional: For services needing TOML
    └── deployment.toml          # Auto-exported from deployment.ncl
```

### macOS (Application Support)

```bash
# Platform-specific location
~/Library/Application Support/provisioning/

# Same structure as Linux
~/Library/Application Support/provisioning/
├── system.ncl                   # Source of truth (Nickel)
├── user_preferences.ncl         # Source of truth (Nickel)
├── platform/
│   └── deployment.ncl           # Source of truth (Nickel)
└── generated/                   # Optional
    └── deployment.toml
```

### Key Principle

**Nickel is source of truth** - All `.ncl` files are authoritative, type-safe configurations validated by `nickel typecheck`. TOML files (if
generated) are optional output only, never edited directly.

---

## What Happens During Setup

### Step 1: System Detection

Provisioning detects:
- **OS**: macOS or Linux (Darwin detection)
- **Architecture**: aarch64 or x86_64
- **CPU Count**: Number of processors
- **Memory**: Total system RAM in GB
- **Disk Space**: Total available disk

```bash
# View detected system
provisioning setup detect --verbose
```

### Step 2: Profile Selection

You choose between:
- **Developer**: Fast local setup, Docker Compose
- **Production**: Full validation, Kubernetes/SSH, HA ready
- **CI/CD**: Ephemeral, automated, no interaction

### Step 3: Config Generation (Nickel-Based)

Setup creates Nickel configs using composition:

```nickel
# Example: system.ncl is composed from:
let helpers = import "../../schemas/platform/common/helpers.ncl"
let defaults = import "../../schemas/platform/defaults/system-defaults.ncl"

helpers.compose_config defaults {} {
  os_name = 'macos,
  cpu_count = 8,
  memory_total_gb = 16,
  setup_date = "2026-01-13T12:00:00Z"
}
| system_schema.SystemConfig  # Type contract validation
```

Result: **Type-safe config**, guaranteed valid structure and values.

### Step 4: Validation (Mandatory)

All configs are validated:

```toml
# Done automatically during setup
nickel typecheck ~/.config/provisioning/system.ncl
nickel typecheck ~/.config/provisioning/platform/deployment.ncl

# You can verify anytime
nickel typecheck ~/.config/provisioning/**/*.ncl
```

### Step 5: Service Bootstrap (Profile-Dependent)

**Developer**: Starts Docker Compose services locally
```bash
docker-compose up -d orchestrator control-center kms
```

**Production**: Outputs Kubernetes manifests (doesn't auto-start, you review first)
```yaml
cat ~/.config/provisioning/platform/deployment.ncl
# Review, then deploy to your cluster
kubectl apply -f generated-from-deployment.ncl
```

**CI/CD**: Starts ephemeral Docker Compose in `/tmp`
```bash
# Automatic cleanup on job exit
docker-compose -f /tmp/provisioning-ci-${JOB_ID}/compose.yml up
# Tests run, cleanup automatic on script exit
```

---

## Profile Comparison Details

### Developer Profile

**Goal**: Working provisioning system in less than 5 minutes, minimal configuration

**What gets created**:
- System config (auto-detected, no prompts)
- User preferences (recommended defaults)
- Docker Compose deployment (local mode)
- Local provider (no credentials needed)

**Security**:
- All configs validated (Nickel typecheck)
- Services use secure defaults
- No external API keys needed
- Passwords auto-generated and stored locally

**Time**: 3-4 minutes

**Example**:
```bash
provisioning setup profile --profile developer

# Output:
# ✓ Detected: macOS, aarch64, 8 CPU, 16GB RAM
# ✓ Created: ~/.config/provisioning/system.ncl
# ✓ Created: ~/.config/provisioning/platform/deployment.ncl
# ✓ Validated: All configs passed typecheck
# ✓ Started: orchestrator (port 9090)
# ✓ Started: control-center (port 3000)
# ✓ Started: kms (port 3001)
# ✓ Ready in 3 minutes 45 seconds
```

### Production Profile

**Goal**: HA-ready, validated, secure deployment with full control

**What gets created**:
- System config (auto-detected)
- User preferences (security-focused: MFA enabled, audit on)
- Kubernetes or SSH deployment (your choice)
- Cloud provider config (UpCloud, AWS, Hetzner, or local)
- Workspace infrastructure (full IaC definitions)
- Cedar authorization policies (fine-grained RBAC)

**Security**:
- All configs validated (Nickel typecheck)
- Requires system minimums: 4+ CPU, 8+ GB RAM
- MFA enabled by default (can configure)
- Audit logging enabled (captures all operations)
- Cedar policies for authorization
- Credentials stored encrypted (RustyVault)

**Time**: 10-15 minutes (interactive, many questions)

**Example**:
```bash
provisioning setup profile --profile production --interactive

# Prompts:
# Profile: Production ✓
# Deployment mode? (kubernetes/ssh): kubernetes
# Cloud provider? (upcloud/aws/hetzner/local): upcloud
# Workspace name? my-prod-infra
# Enable MFA? (y/n): y
# Enable audit logging? (y/n): y
# Number of master nodes? (1-5): 3
# Worker node count? (2-10): 5

# Output (15 minutes later):
# ✓ Created: ~/.config/provisioning/system.ncl
# ✓ Created: ~/.config/provisioning/platform/deployment.ncl
# ✓ Created: ~/.config/provisioning/providers/upcloud.ncl
# ✓ Created: workspace-prod-infra/infrastructure.ncl
# ✓ Created: cedar-policies/default.cedar
# ✓ Validated: All configs passed typecheck
# ✓ Services NOT started (you'll deploy to cluster)
# ✓ Ready for Kubernetes deployment
```

### CI/CD Profile

**Goal**: Minimal setup, no interaction, auto-cleanup for pipelines

**What gets created**:
- System config (minimal, CI environment)
- Deployment config (ephemeral, auto-cleanup)
- Docker Compose (no Kubernetes overhead)
- Runs in /tmp (temporary directory)

**Security**:
- All configs validated (Nickel typecheck)
- No persistent state (by design)
- Uses CI environment variables for secrets
- Auto-cleanup on job completion
- No credentials stored locally

**Time**: Less than 2 minutes

**Example**:
```bash
# In GitHub Actions:
- name: Setup Provisioning
  run: |
    export PROVISIONING_PROVIDER=local
    provisioning setup profile --profile cicd

# Output:
# ✓ Created: /tmp/provisioning-ci-abc123/
# ✓ Validated: All configs passed typecheck
# ✓ Started: Docker Compose services
# ✓ Services ready for tests
# Services will auto-cleanup on job exit
```

---

## Verification

### After Setup, Verify Everything Works

**Developer Profile**:
```bash
# Check configs exist
ls -la ~/.config/provisioning/
ls -la ~/.config/provisioning/platform/

# Verify Nickel validation
nickel typecheck ~/.config/provisioning/system.ncl
nickel typecheck ~/.config/provisioning/platform/deployment.ncl

# Test services
curl http://localhost:9090/health
curl http://localhost:3000/health
curl http://localhost:3001/health

# Expected: HTTP 200 with {"status": "healthy"}
```

**Production Profile**:
```bash
# Check Nickel configs
nickel typecheck ~/.config/provisioning/system.ncl
nickel typecheck ~/.config/provisioning/platform/deployment.ncl
nickel typecheck ~/.config/provisioning/providers/upcloud.ncl

# View deployment config
cat ~/.config/provisioning/platform/deployment.ncl

# View infrastructure definition
cat workspace-my-prod-infra/infrastructure.ncl

# View authorization policies
cat ~/.config/provisioning/cedar-policies/default.cedar
```

**CI/CD Profile**:
```bash
# Check temp configs exist
ls -la /tmp/provisioning-ci-*/

# Verify Nickel validation passed
nickel typecheck /tmp/provisioning-ci-*/platform/deployment.ncl

# Services should be running
docker ps | grep provisioning
```

---

## Troubleshooting

### Issue: "Nickel not found"

**Cause**: Nickel binary not installed

**Solution**:
```nickel
# macOS
brew install nickel

# Linux (Arch)
pacman -S nickel

# From source
git clone https://github.com/nickel-lang/nickel
cd nickel && cargo install --path .

# Verify
nickel --version  # Should be 1.5.0+
```

### Issue: "Configuration validation failed"

**Cause**: Nickel typecheck error in generated config

**Solution**:
```nickel
# See detailed error
nickel typecheck ~/.config/provisioning/platform/deployment.ncl --color always

# Common issues:
# - Missing required field (check schema)
# - Wrong type (string vs number)
# - Enum value not in allowed list

# Delete and retry setup
rm -rf ~/.config/provisioning/
provisioning setup profile --profile developer --verbose
```

### Issue: "Docker not available" (Developer Profile)

**Cause**: Docker not installed or not running

**Solution**:
```bash
# Check Docker
docker --version
docker ps

# macOS: Install Docker Desktop
brew install --cask docker

# Linux: Install Docker
sudo apt-get install docker.io  # Ubuntu/Debian
sudo pacman -S docker           # Arch

# Start Docker
sudo systemctl start docker

# Retry setup
provisioning setup profile --profile developer
```

### Issue: "Services won't start"

**Cause**: Port already in use, Docker not running, or resource constraints

**Solution**:
```bash
# Check what's using ports 9090, 3000, 3001
lsof -i :9090
lsof -i :3000
lsof -i :3001

# Stop conflicting service or wait for it to release port

# Stop and restart provisioning services
docker-compose down
docker-compose up -d

# Check Docker resources
docker stats
docker system prune  # Free up space if needed
```

### Issue: "Permission denied" on config directory

**Cause**: Directory created with wrong permissions

**Solution**:
```bash
# Fix permissions (macOS)
chmod 700 ~/Library/Application\ Support/provisioning/

# Fix permissions (Linux)
chmod 700 ~/.config/provisioning/

# Fix nested directories
chmod 700 ~/.config/provisioning/*

# Retry setup
provisioning setup profile --profile developer
```

### Issue: "Wrong configuration being used"

**Cause**: Services reading from old location or wrong environment variable

**Solution**:
```bash
# Verify service sees new location
echo $PROVISIONING_CONFIG
# Should be: ~/.config/provisioning/platform/deployment.ncl

# Set explicitly if needed
export PROVISIONING_CONFIG=~/.config/provisioning/platform/deployment.ncl
provisioning service restart

# Check what service is actually loading
provisioning service status --verbose
```

---

## Using Workspace-Specific Overrides

After initial setup, you can customize configs per workspace:

```toml
# Create workspace-specific override
mkdir -p workspace-myproject/config
cat > workspace-myproject/config/platform-overrides.ncl <<'EOF'
{
  orchestrator.server.port = 9999,
  orchestrator.workspace.name = "myproject",
  vault-service.storage.path = "./workspace-myproject/data/vault"
}
EOF

# Services will merge this with the base config
provisioning workspace activate myproject
provisioning platform deploy  # Uses merged config
```

---

## Next Steps

After setup:

1. **Create a Workspace**
   ```bash
   provisioning workspace create myapp
   ```

2. **Deploy Your First Service**
   ```bash
   provisioning service deploy nginx
   ```

3. **Configure Monitoring**
   ```bash
   provisioning monitor setup prometheus
   ```

4. **Set Up CI/CD Integration**
   ```bash
   provisioning ci configure github
   ```

5. **Learn Advanced Configuration**
   - See: [Setup Profiles Guide](setup-profiles.md)
   - See: [Platform Configuration](05-platform-configuration.md)
   - See: [Nickel Configuration](../configuration/nickel-configuration.md)

---

## Key Concepts

### Type-Safe Configuration (Nickel)

All configs use Nickel type contracts:
- Field names and types enforced
- Enum values validated
- Invalid configs caught at nickel typecheck time
- No runtime surprises

### Platform-Specific Paths

Configs stored in platform-standard locations:
- **Linux**: `~/.config/provisioning/` (XDG Base Directory)
- **macOS**: `~/Library/Application Support/provisioning/`
- Respects `$XDG_CONFIG_HOME` override on Linux

### Composition Pattern

Configs built from:
1. **Base defaults** (provisioning/schemas/platform/defaults/)
2. **Profile overlay** (developer/production/cicd specific)
3. **User customization** (optional, via Nickel import)

Result: Minimal, validated, reproducible config.

### Ephemeral vs. Persistent

- **Developer/Production**: Persistent in home directory
- **CI/CD**: Ephemeral in /tmp, auto-cleanup

---

## Getting Help

```bash
# Help for setup
provisioning setup --help

# Help for profiles
provisioning setup profile --help

# Interactive debugging
provisioning setup profile --profile developer --verbose

# Validate configuration
provisioning setup validate

# View detected capabilities
provisioning setup detect --verbose

# Check platform status
provisioning platform status

# View logs
provisioning service logs orchestrator
provisioning service logs control-center
provisioning service logs kms
```

---

**Ready?** Run: `provisioning setup profile` and choose your profile!

**Questions?** Check [Troubleshooting](../troubleshooting/troubleshooting.md) or [Setup Profiles Guide](setup-profiles.md)