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

# Setup Profiles Guide - Detailed Reference

This guide provides detailed information about each setup profile and when to use them.

---

## Profile Comparison Matrix

|  | Aspect | Developer | Production | CI/CD |  |
|  | -------- | ----------- | ----------- | ------- |  |
|  | **Duration** | 3-4 min | 10-15 min | <2 min |  |
|  | **User Input** | Minimal (1 question) | Extensive (10+ questions) | None (env vars) |  |
|  | **Config Type** | Nickel (auto-composed) | Nickel (interactive) | Nickel (auto-minimal) |  |
|  | **Validation** | Nickel typecheck | Nickel typecheck | Nickel typecheck |  |
|  | **Deployment** | Docker Compose | Kubernetes/SSH/Docker | Docker Compose |  |
|  | **Services Started** | Auto-start locally | Manual (you deploy) | Auto-start ephemeral |  |
|  | **Storage** | Home dir (persistent) | Home dir (persistent) | /tmp (ephemeral) |  |
|  | **Security** | Local defaults | MFA+Audit+Policies | Env vars + CI secrets |  |
|  | **Intended User** | Developer, learner | Production operator | CI/CD automation |  |
|  | **Best For** | Local testing, prototyping | Team deployments, HA | Automated testing |  |

---

## Developer Profile: Fast Local Setup

### When to Use

- **First-time users**: Get provisioning working quickly
- **Local development**: Test infrastructure on your machine
- **Learning**: Understand provisioning concepts
- **Prototyping**: Rapid iteration on configurations
- **Single-user setup**: Personal workstation only

### What Gets Created

**Config Files** (all Nickel, type-safe):
- `system.ncl` - System detection (auto-detected, read-only)
- `user_preferences.ncl` - User settings (recommended defaults)
- `platform/deployment.ncl` - Local Docker Compose setup
- `providers/local.ncl` - Local provider (no credentials)

**Services** (Docker Compose):
- Orchestrator (port 9090)
- Control Center (port 3000)
- KMS service (port 3001)

**Storage Location**:
- macOS: `~/Library/Application Support/provisioning/`
- Linux: `~/.config/provisioning/`

### System Requirements

**Minimum**:
- OS: macOS (10.14+) or Linux
- CPU: 2 cores
- Memory: 4 GB RAM
- Disk: 2 GB free

**Recommended**:
- CPU: 4+ cores
- Memory: 8+ GB RAM
- Disk: 10 GB free

**Dependencies**:
- Nushell (0.109.0+)
- Nickel (1.5.0+)
- Docker (latest)

### Step-by-Step Walkthrough

#### Step 1: Run Setup

```text
provisioning setup profile --profile developer
```

Output:
```text
╔═══════════════════════════════════════════════════════╗
║    PROVISIONING SYSTEM SETUP - DEVELOPER PROFILE      ║
╚═══════════════════════════════════════════════════════╝

Environment Detection
  OS: macOS (15.2.0)
  Architecture: aarch64
  CPU Count: 8
  Memory: 16 GB
  Disk: 500 GB

✓ Detected capabilities: Docker
✓ Configuration location: ~/Library/Application Support/provisioning/

Setup Profile: DEVELOPER
```

#### Step 2: Auto-Detection

System automatically detects:
- Operating system (macOS/Linux)
- Architecture (aarch64/x86_64)
- CPU and memory
- Available deployment tools (Docker, Kubernetes, etc.)

**You see**: Detection summary, no prompts

#### Step 3: Configuration Generation

Creates three Nickel configs:

**system.ncl** - System info (read-only):
```text
{
  version = "1.0.0",
  config_base_path = "/Users/user/Library/Application Support/provisioning",
  os_name = 'macos,
  os_version = "15.2.0",
  system_architecture = 'aarch64,
  cpu_count = 8,
  memory_total_gb = 16,
  disk_total_gb = 500,
  setup_date = "2026-01-13T12:34:56Z"
}
| SystemConfig
```

**platform/deployment.ncl** - Deployment config (can edit):
```text
{
  deployment = {
    mode = 'docker_compose,
    location_type = 'local,
  },
  services = {
    orchestrator = {
      endpoint = "http://localhost:9090/health",
      timeout_seconds = 30,
    },
    control_center = {
      endpoint = "http://localhost:3000/health",
      timeout_seconds = 30,
    },
    kms_service = {
      endpoint = "http://localhost:3001/health",
      timeout_seconds = 30,
    },
  },
}
| DeploymentConfig
```

**user_preferences.ncl** - User settings (can edit):
```text
{
  output_format = 'yaml,
  use_colors = true,
  confirm_delete = true,
  default_log_level = 'info,
  http_timeout_seconds = 30,
}
| UserPreferencesConfig
```

#### Step 4: Validation

Each config is validated:
```text
✓ Validating system.ncl
✓ Validating platform/deployment.ncl
✓ Validating user_preferences.ncl
✓ All configurations validated: PASSED
```

#### Step 5: Service Startup

Docker Compose starts:
```text
✓ Starting Docker Compose services...
✓ Starting orchestrator... [port 9090]
✓ Starting control-center... [port 3000]
✓ Starting kms... [port 3001]
```

#### Step 6: Verification

Health checks verify services:
```text
✓ Orchestrator health: HEALTHY
✓ Control Center health: HEALTHY
✓ KMS health: HEALTHY

Setup complete in 3 minutes 47 seconds!
```

### After Setup: Common Tasks

**Verify everything works**:
```text
curl http://localhost:9090/health
curl http://localhost:3000/health
curl http://localhost:3001/health
```

**View your configuration**:
```text
cat ~/Library/Application\ Support/provisioning/system.ncl
cat ~/Library/Application\ Support/provisioning/platform/deployment.ncl
```

**Create a workspace**:
```text
provisioning workspace create myapp
```

**View logs**:
```text
docker-compose logs orchestrator
docker-compose logs control-center
docker-compose logs kms
```

**Stop services**:
```text
docker-compose down
```

---

## Production Profile: Enterprise-Ready Deployment

### When to Use

- **Production deployments**: Going live
- **Team environments**: Multiple users, shared infrastructure
- **High availability**: Kubernetes clusters
- **Security requirements**: MFA, audit logging, policies
- **Multi-cloud**: UpCloud, AWS, Hetzner
- **Compliance**: Audit trails, authorization policies

### What Gets Created

**Config Files** (all Nickel, type-safe):
- `system.ncl` - System detection (auto-detected)
- `user_preferences.ncl` - Security-focused defaults (MFA, audit enabled)
- `platform/deployment.ncl` - Kubernetes/SSH configuration
- `providers/upcloud.ncl` (or aws/hetzner) - Cloud provider credentials
- `cedar-policies/default.cedar` - Authorization policies (Cedar format)
- `workspace-*/infrastructure.ncl` - Infrastructure-as-Code definitions

**Services**: You deploy to Kubernetes or SSH manually

**Storage Location**:
- macOS: `~/Library/Application Support/provisioning/`
- Linux: `~/.config/provisioning/`

### System Requirements

**Minimum**:
- OS: macOS (10.14+) or Linux
- CPU: 4 cores
- Memory: 8 GB RAM
- Disk: 10 GB free

**Recommended**:
- CPU: 8+ cores
- Memory: 16+ GB RAM
- Disk: 50 GB free
- Cloud account (UpCloud, AWS, or Hetzner)

**Dependencies**:
- Nushell (0.109.0+)
- Nickel (1.5.0+)
- Docker (for building)
- kubectl (for Kubernetes deployment)
- Cloud CLI (upcloud-cli, aws-cli, etc.)

### Step-by-Step Walkthrough

#### Step 1: Run Setup

```text
provisioning setup profile --profile production --interactive
```

#### Step 2: System Detection

Same as Developer profile - auto-detects OS, CPU, memory, etc.

#### Step 3: Interactive Configuration

The wizard asks 10-15 questions:

```text
1. Deployment Mode?
   a) Kubernetes (recommended for HA)
   b) SSH (manual server management)
   c) Docker Compose (hybrid local/remote)
   → Your choice: a) Kubernetes

2. Cloud Provider?
   a) UpCloud
   b) AWS
   c) Hetzner
   d) Local (self-managed servers)
   → Your choice: a) UpCloud

3. Workspace Name?
   (names your infrastructure project)
   → Your input: production-infrastructure

4. Kubernetes Cluster?
   a) Create new cluster
   b) Use existing cluster
   → Your choice: a) Create new

5. Master Nodes Count? (1-5, default 3)
   (for HA, recommend 3 or 5)
   → Your input: 3

6. Worker Nodes Count? (2-10, default 5)
   (for scalability)
   → Your input: 5

7. Enable MFA?
   (Multi-factor authentication for access)
   → Your choice: y

8. Enable Audit Logging?
   (Log all operations for compliance)
   → Your choice: y

9. Storage Backend?
   a) etcd (Kubernetes default)
   b) PostgreSQL (external)
   c) S3-compatible (cloud)
   → Your choice: a) etcd

10. Certificate Management?
    a) Let's Encrypt (auto-renew)
    b) Self-signed (for testing)
    c) Bring your own
    → Your choice: a) Let's Encrypt

11. Monitoring?
    a) Prometheus + Grafana
    b) Datadog
    c) CloudWatch
    d) None (not recommended)
    → Your choice: a) Prometheus + Grafana

12. Logging?
    a) ELK Stack
    b) Splunk
    c) CloudWatch Logs
    d) None
    → Your choice: a) ELK Stack

13. Authorization?
    a) Cedar policies (fine-grained)
    b) RBAC (basic roles)
    c) ABAC (attribute-based)
    → Your choice: a) Cedar policies
```

#### Step 4: Configuration Generation

Creates extensive Nickel configs:

**platform/deployment.ncl**:
```text
{
  deployment = {
    mode = 'kubernetes,
    cluster_type = 'multi_master,
    master_count = 3,
    worker_count = 5,
    ha_enabled = true,
  },
  security = {
    mfa_enabled = true,
    audit_logging = true,
    tls_enabled = true,
    certificate_provider = 'letsencrypt,
  },
  monitoring = {
    prometheus_enabled = true,
    grafana_enabled = true,
  },
  logging = {
    elk_enabled = true,
  },
}
| ProductionDeploymentConfig
```

**providers/upcloud.ncl**:
```text
{
  provider = 'upcloud,
  api_key_ref = "rustyvault://secrets/upcloud/api-key",
  api_secret_ref = "rustyvault://secrets/upcloud/api-secret",
  region = "us-east-1",
  server_template = "ubuntu-22.04",
}
| UpCloudProviderConfig
```

**cedar-policies/default.cedar**:
```text
permit(
  principal == User::"john@company.com",
  action == Action::"Deploy",
  resource == Workspace::"prod-infra"
)
when { principal.mfa_verified == true };

permit(
  principal in Group::"DevOps",
  action == Action::"ReadMetrics",
  resource in Team::"*"
);

forbid(
  principal in Group::"Contractors",
  action == Action::"DeleteWorkspace",
  resource in Team::"*"
);
```

#### Step 5: Validation

All configs validated:
```text
✓ Validating system.ncl
✓ Validating platform/deployment.ncl
✓ Validating providers/upcloud.ncl
✓ Validating cedar-policies/default.cedar
✓ All configurations validated: PASSED
```

#### Step 6: Summary & Confirmation

```text
Setup Summary
─────────────────────────────────────────
Profile:           Production
Deployment Mode:   Kubernetes
Cloud Provider:    UpCloud
Master Nodes:      3
Worker Nodes:      5
MFA Enabled:       Yes
Audit Logging:     Yes
Monitoring:        Prometheus + Grafana
Logging:           ELK Stack

Do you want to proceed? (y/n): y
```

#### Step 7: Infrastructure Creation (Optional)

```text
Creating UpCloud infrastructure...
  Creating 3 master nodes... [networking configured]
  Creating 5 worker nodes... [networking configured]
  Deploying Kubernetes... [cluster bootstrap]
  Installing monitoring... [Prometheus configured]
  Installing logging... [ELK deployed]

Infrastructure ready in ~12 minutes!

Kubernetes cluster access:
  kubectl config use-context provisioning-prod-infra
  kubectl cluster-info

Deploy services:
  kubectl apply -f infrastructure.ncl
```

### After Setup: Common Tasks

**View Kubernetes cluster**:
```text
kubectl get nodes
kubectl get pods --all-namespaces
```

**Check Cedar authorization**:
```text
cat ~/.config/provisioning/cedar-policies/default.cedar
```

**View infrastructure definition**:
```text
cat workspace-production-infrastructure/infrastructure.ncl
```

**Deploy an application**:
```text
provisioning app deploy myapp --workspace production-infrastructure
```

**Monitor cluster**:
```text
# Access Grafana
open http://localhost:3000

# View Prometheus metrics
open http://localhost:9090
```

---

## CI/CD Profile: Ephemeral Automated Setup

### When to Use

- **GitHub Actions workflows**: Test infrastructure changes
- **GitLab CI pipelines**: Automated testing
- **Jenkins jobs**: Integration testing
- **Automated testing**: Spin up, test, cleanup
- **Ephemeral environments**: No persistent state

### What Gets Created

**Config Files** (minimal Nickel):
- `system.ncl` - CI environment info
- `platform/deployment.ncl` - Minimal Docker Compose
- `providers/local.ncl` - No credentials

**Services**: Docker Compose (temporary)

**Storage Location**: `/tmp/provisioning-ci-<job-id>/`

### System Requirements

**Minimal** (CI container):
- OS: Any Linux
- CPU: 1+ core
- Memory: 2 GB RAM
- Disk: 1 GB free

**Dependencies**:
- Nushell (0.109.0+)
- Nickel (1.5.0+)
- Docker or Podman

### Step-by-Step Walkthrough

#### Example: GitHub Actions

```text
name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Nushell
        run: |
          sudo apt-get update
          sudo apt-get install -y nushell

      - name: Install Nickel
        run: |
          sudo apt-get install -y nickel

      - name: Install Provisioning
        run: |
          git clone https://github.com/project-provisioning/provisioning
          cd provisioning
          ./scripts/install.sh

      - name: Setup Provisioning (CI/CD Profile)
        run: |
          export PROVISIONING_PROVIDER=local
          export PROVISIONING_WORKSPACE=ci-test-${{ github.run_id }}
          provisioning setup profile --profile cicd

      - name: Run Integration Tests
        run: |
          # Services are now running
          curl http://localhost:9090/health
          curl http://localhost:3000/health

          # Run your tests
          ./tests/integration-test.sh

      - name: Cleanup
        if: always()
        run: |
          docker-compose down
          # Automatic cleanup on job exit
```

#### What Happens

**Step 1: Minimal Detection**
```text
✓ Detected: CI environment
✓ Profile: CICD
```

**Step 2: Ephemeral Config Creation**
```text
✓ Created: /tmp/provisioning-ci-abc123def456/
✓ Created: /tmp/provisioning-ci-abc123def456/system.ncl
✓ Created: /tmp/provisioning-ci-abc123def456/platform/deployment.ncl
```

**Step 3: Validation**
```text
✓ Validating system.ncl
✓ Validating platform/deployment.ncl
✓ All configurations validated: PASSED
```

**Step 4: Services Start**
```text
✓ Starting Docker Compose services
✓ Orchestrator running [port 9090]
✓ Control Center running [port 3000]
✓ KMS running [port 3001]
✓ Services ready for tests
```

**Step 5: Tests Execute**
```text
$ curl http://localhost:9090/health
{"status": "healthy", "uptime": "2s"}

$ ./tests/integration-test.sh
Test: API endpoint... PASSED
Test: Database schema... PASSED
Test: Service discovery... PASSED
All tests passed!
```

**Step 6: Automatic Cleanup**
```text
✓ Cleanup triggered (job exit)
✓ Stopping Docker Compose
✓ Removing temporary directory: /tmp/provisioning-ci-abc123def456/
✓ Cleanup complete
```

### CI/CD Environment Variables

Use environment variables to customize:

```text
# Provider (local or cloud)
export PROVISIONING_PROVIDER=local|upcloud|aws|hetzner

# Workspace name
export PROVISIONING_WORKSPACE=ci-test-${BUILD_ID}

# Skip confirmations
export PROVISIONING_YES=true

# Enable verbose output
export PROVISIONING_VERBOSE=true

# Custom config location (if needed)
export PROVISIONING_CONFIG=/tmp/custom-config.ncl
```

### CI/CD Best Practices

**1. Use matrix builds for testing**:
```text
strategy:
  matrix:
    profile: [developer, production]
    provider: [local, aws]
```

**2. Cache Nickel compilation**:
```text
- uses: actions/cache@v3
  with:
    path: ~/.cache/nickel
    key: nickel-${{ hashFiles('*.ncl') }}
```

**3. Separate test stages**:
```text
- name: Setup (CI/CD Profile)
- name: Test Unit
- name: Test Integration
- name: Test E2E
```

**4. Publish test results**:
```text
- name: Publish Test Results
  if: always()
  uses: actions/upload-artifact@v3
  with:
    name: test-results
    path: test-results/
```

---

## Profile Selection Guide

### "Which profile should I choose?"

**Start with Developer if**:
- You're new to provisioning
- You're testing locally
- You want to understand how it works
- You need quick feedback loops

**Move to Production if**:
- You're deploying to production
- You need high availability
- You have security requirements
- You're managing a team
- You need audit logging

**Use CI/CD if**:
- You're running automated tests
- You're in a CI/CD pipeline
- You want ephemeral environments
- You don't need persistent state

### Migration Path

```text
Developer → Production
  (ready for team)
     ↓
     └→ CI/CD (for testing)
```

You can run Developer locally and CI/CD in your pipeline simultaneously.

---

## Modifying Profiles After Setup

### Developer → Production Migration

If you started with Developer and want to move to Production:

```text
# Backup your current setup
tar czf provisioning-backup.tar.gz ~/.config/provisioning/

# Run production setup
provisioning setup profile --profile production --interactive

# Migrate any customizations from backup
tar xzf provisioning-backup.tar.gz
# Merge configs manually
```

### Customizing Profile Configs

All profiles' Nickel configs can be edited after setup:

```text
# Edit deployment config
vim ~/.config/provisioning/platform/deployment.ncl

# Validate changes
nickel typecheck ~/.config/provisioning/platform/deployment.ncl

# Apply changes
docker-compose restart  # or kubectl apply -f
```

---

## Troubleshooting Profile-Specific Issues

### Developer Profile

**Problem**: Docker not running
```text
# Solution: Start Docker
docker daemon &
# or
sudo systemctl start docker
```

**Problem**: Ports 9090/3000/3001 already in use
```text
# Solution: Kill conflicting process
lsof -i :9090 | grep LISTEN | awk '{print $2}' | xargs kill -9
```

### Production Profile

**Problem**: Kubernetes not installed
```text
# Solution: Install kubectl
brew install kubectl  # macOS
sudo apt-get install kubectl  # Linux
```

**Problem**: Cloud credentials rejected
```text
# Solution: Verify credentials
upcloud auth status  # or aws sts get-caller-identity
# Re-run setup with correct credentials
```

### CI/CD Profile

**Problem**: Services not accessible from test
```text
# Solution: Use service DNS
curl http://orchestrator:9090/health  # instead of localhost
```

**Problem**: Cleanup not working
```text
# Solution: Manual cleanup
docker system prune -f
rm -rf /tmp/provisioning-ci-*/
```

---

| **Next Step**: Choose your profile and run `provisioning setup profile --profile <developer | production | cicd>` |

**Need more help?** See [Setup Guide](setup.md) or [Troubleshooting](../troubleshooting/troubleshooting.md)