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

provisioning setup profile --profile developer

Output:

╔═══════════════════════════════════════════════════════╗
║    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):

{
  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):

{
  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):

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

✓ Validating system.ncl
✓ Validating platform/deployment.ncl
✓ Validating user_preferences.ncl
✓ All configurations validated: PASSED

Step 5: Service Startup

Docker Compose starts:

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

Step 6: Verification

Health checks verify services:

✓ Orchestrator health: HEALTHY
✓ Control Center health: HEALTHY
✓ KMS health: HEALTHY

Setup complete in 3 minutes 47 seconds!

After Setup: Common Tasks

Verify everything works:

curl http://localhost:9090/health
curl http://localhost:3000/health
curl http://localhost:3001/health

View your configuration:

cat ~/Library/Application\ Support/provisioning/system.ncl
cat ~/Library/Application\ Support/provisioning/platform/deployment.ncl

Create a workspace:

provisioning workspace create myapp

View logs:

docker-compose logs orchestrator
docker-compose logs control-center
docker-compose logs kms

Stop services:

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

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:

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:

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

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

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:

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

Step 6: Summary & Confirmation

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)

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:

kubectl get nodes
kubectl get pods --all-namespaces

Check Cedar authorization:

cat ~/.config/provisioning/cedar-policies/default.cedar

View infrastructure definition:

cat workspace-production-infrastructure/infrastructure.ncl

Deploy an application:

provisioning app deploy myapp --workspace production-infrastructure

Monitor cluster:

# 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

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

✓ Detected: CI environment
✓ Profile: CICD

Step 2: Ephemeral Config Creation

✓ Created: /tmp/provisioning-ci-abc123def456/
✓ Created: /tmp/provisioning-ci-abc123def456/system.ncl
✓ Created: /tmp/provisioning-ci-abc123def456/platform/deployment.ncl

Step 3: Validation

✓ Validating system.ncl
✓ Validating platform/deployment.ncl
✓ All configurations validated: PASSED

Step 4: Services Start

✓ 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

$ 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

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

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

strategy:
  matrix:
    profile: [developer, production]
    provider: [local, aws]

2. Cache Nickel compilation:

- uses: actions/cache@v3
  with:
    path: ~/.cache/nickel
    key: nickel-${{ hashFiles('*.ncl') }}

3. Separate test stages:

- name: Setup (CI/CD Profile)
- name: Test Unit
- name: Test Integration
- name: Test E2E

4. Publish test results:

- 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

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:

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

# 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

# Solution: Start Docker
docker daemon &
# or
sudo systemctl start docker

Problem: Ports 9090/3000/3001 already in use

# Solution: Kill conflicting process
lsof -i :9090 | grep LISTEN | awk '{print $2}' | xargs kill -9

Production Profile

Problem: Kubernetes not installed

# Solution: Install kubectl
brew install kubectl  # macOS
sudo apt-get install kubectl  # Linux

Problem: Cloud credentials rejected

# 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

# Solution: Use service DNS
curl http://orchestrator:9090/health  # instead of localhost

Problem: Cleanup not working

# 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 or Troubleshooting