# Setup Profiles Guide - Detailed Reference\n\nThis guide provides detailed information about each setup profile and when to use them.\n\n---\n\n## Profile Comparison Matrix\n\n|  | Aspect | Developer | Production | CI/CD |  |\n|  | -------- | ----------- | ----------- | ------- |  |\n|  | **Duration** | 3-4 min | 10-15 min | <2 min |  |\n|  | **User Input** | Minimal (1 question) | Extensive (10+ questions) | None (env vars) |  |\n|  | **Config Type** | Nickel (auto-composed) | Nickel (interactive) | Nickel (auto-minimal) |  |\n|  | **Validation** | Nickel typecheck | Nickel typecheck | Nickel typecheck |  |\n|  | **Deployment** | Docker Compose | Kubernetes/SSH/Docker | Docker Compose |  |\n|  | **Services Started** | Auto-start locally | Manual (you deploy) | Auto-start ephemeral |  |\n|  | **Storage** | Home dir (persistent) | Home dir (persistent) | /tmp (ephemeral) |  |\n|  | **Security** | Local defaults | MFA+Audit+Policies | Env vars + CI secrets |  |\n|  | **Intended User** | Developer, learner | Production operator | CI/CD automation |  |\n|  | **Best For** | Local testing, prototyping | Team deployments, HA | Automated testing |  |\n\n---\n\n## Developer Profile: Fast Local Setup\n\n### When to Use\n\n- **First-time users**: Get provisioning working quickly\n- **Local development**: Test infrastructure on your machine\n- **Learning**: Understand provisioning concepts\n- **Prototyping**: Rapid iteration on configurations\n- **Single-user setup**: Personal workstation only\n\n### What Gets Created\n\n**Config Files** (all Nickel, type-safe):\n- `system.ncl` - System detection (auto-detected, read-only)\n- `user_preferences.ncl` - User settings (recommended defaults)\n- `platform/deployment.ncl` - Local Docker Compose setup\n- `providers/local.ncl` - Local provider (no credentials)\n\n**Services** (Docker Compose):\n- Orchestrator (port 9090)\n- Control Center (port 3000)\n- KMS service (port 3001)\n\n**Storage Location**:\n- macOS: `~/Library/Application Support/provisioning/`\n- Linux: `~/.config/provisioning/`\n\n### System Requirements\n\n**Minimum**:\n- OS: macOS (10.14+) or Linux\n- CPU: 2 cores\n- Memory: 4 GB RAM\n- Disk: 2 GB free\n\n**Recommended**:\n- CPU: 4+ cores\n- Memory: 8+ GB RAM\n- Disk: 10 GB free\n\n**Dependencies**:\n- Nushell (0.109.0+)\n- Nickel (1.5.0+)\n- Docker (latest)\n\n### Step-by-Step Walkthrough\n\n#### Step 1: Run Setup\n\n```\nprovisioning setup profile --profile developer\n```\n\nOutput:\n```\n╔═══════════════════════════════════════════════════════╗\n║    PROVISIONING SYSTEM SETUP - DEVELOPER PROFILE      ║\n╚═══════════════════════════════════════════════════════╝\n\nEnvironment Detection\n  OS: macOS (15.2.0)\n  Architecture: aarch64\n  CPU Count: 8\n  Memory: 16 GB\n  Disk: 500 GB\n\n✓ Detected capabilities: Docker\n✓ Configuration location: ~/Library/Application Support/provisioning/\n\nSetup Profile: DEVELOPER\n```\n\n#### Step 2: Auto-Detection\n\nSystem automatically detects:\n- Operating system (macOS/Linux)\n- Architecture (aarch64/x86_64)\n- CPU and memory\n- Available deployment tools (Docker, Kubernetes, etc.)\n\n**You see**: Detection summary, no prompts\n\n#### Step 3: Configuration Generation\n\nCreates three Nickel configs:\n\n**system.ncl** - System info (read-only):\n```\n{\n  version = "1.0.0",\n  config_base_path = "/Users/user/Library/Application Support/provisioning",\n  os_name = 'macos,\n  os_version = "15.2.0",\n  system_architecture = 'aarch64,\n  cpu_count = 8,\n  memory_total_gb = 16,\n  disk_total_gb = 500,\n  setup_date = "2026-01-13T12:34:56Z"\n}\n| SystemConfig\n```\n\n**platform/deployment.ncl** - Deployment config (can edit):\n```\n{\n  deployment = {\n    mode = 'docker_compose,\n    location_type = 'local,\n  },\n  services = {\n    orchestrator = {\n      endpoint = "http://localhost:9090/health",\n      timeout_seconds = 30,\n    },\n    control_center = {\n      endpoint = "http://localhost:3000/health",\n      timeout_seconds = 30,\n    },\n    kms_service = {\n      endpoint = "http://localhost:3001/health",\n      timeout_seconds = 30,\n    },\n  },\n}\n| DeploymentConfig\n```\n\n**user_preferences.ncl** - User settings (can edit):\n```\n{\n  output_format = 'yaml,\n  use_colors = true,\n  confirm_delete = true,\n  default_log_level = 'info,\n  http_timeout_seconds = 30,\n}\n| UserPreferencesConfig\n```\n\n#### Step 4: Validation\n\nEach config is validated:\n```\n✓ Validating system.ncl\n✓ Validating platform/deployment.ncl\n✓ Validating user_preferences.ncl\n✓ All configurations validated: PASSED\n```\n\n#### Step 5: Service Startup\n\nDocker Compose starts:\n```\n✓ Starting Docker Compose services...\n✓ Starting orchestrator... [port 9090]\n✓ Starting control-center... [port 3000]\n✓ Starting kms... [port 3001]\n```\n\n#### Step 6: Verification\n\nHealth checks verify services:\n```\n✓ Orchestrator health: HEALTHY\n✓ Control Center health: HEALTHY\n✓ KMS health: HEALTHY\n\nSetup complete in 3 minutes 47 seconds!\n```\n\n### After Setup: Common Tasks\n\n**Verify everything works**:\n```\ncurl http://localhost:9090/health\ncurl http://localhost:3000/health\ncurl http://localhost:3001/health\n```\n\n**View your configuration**:\n```\ncat ~/Library/Application\ Support/provisioning/system.ncl\ncat ~/Library/Application\ Support/provisioning/platform/deployment.ncl\n```\n\n**Create a workspace**:\n```\nprovisioning workspace create myapp\n```\n\n**View logs**:\n```\ndocker-compose logs orchestrator\ndocker-compose logs control-center\ndocker-compose logs kms\n```\n\n**Stop services**:\n```\ndocker-compose down\n```\n\n---\n\n## Production Profile: Enterprise-Ready Deployment\n\n### When to Use\n\n- **Production deployments**: Going live\n- **Team environments**: Multiple users, shared infrastructure\n- **High availability**: Kubernetes clusters\n- **Security requirements**: MFA, audit logging, policies\n- **Multi-cloud**: UpCloud, AWS, Hetzner\n- **Compliance**: Audit trails, authorization policies\n\n### What Gets Created\n\n**Config Files** (all Nickel, type-safe):\n- `system.ncl` - System detection (auto-detected)\n- `user_preferences.ncl` - Security-focused defaults (MFA, audit enabled)\n- `platform/deployment.ncl` - Kubernetes/SSH configuration\n- `providers/upcloud.ncl` (or aws/hetzner) - Cloud provider credentials\n- `cedar-policies/default.cedar` - Authorization policies (Cedar format)\n- `workspace-*/infrastructure.ncl` - Infrastructure-as-Code definitions\n\n**Services**: You deploy to Kubernetes or SSH manually\n\n**Storage Location**:\n- macOS: `~/Library/Application Support/provisioning/`\n- Linux: `~/.config/provisioning/`\n\n### System Requirements\n\n**Minimum**:\n- OS: macOS (10.14+) or Linux\n- CPU: 4 cores\n- Memory: 8 GB RAM\n- Disk: 10 GB free\n\n**Recommended**:\n- CPU: 8+ cores\n- Memory: 16+ GB RAM\n- Disk: 50 GB free\n- Cloud account (UpCloud, AWS, or Hetzner)\n\n**Dependencies**:\n- Nushell (0.109.0+)\n- Nickel (1.5.0+)\n- Docker (for building)\n- kubectl (for Kubernetes deployment)\n- Cloud CLI (upcloud-cli, aws-cli, etc.)\n\n### Step-by-Step Walkthrough\n\n#### Step 1: Run Setup\n\n```\nprovisioning setup profile --profile production --interactive\n```\n\n#### Step 2: System Detection\n\nSame as Developer profile - auto-detects OS, CPU, memory, etc.\n\n#### Step 3: Interactive Configuration\n\nThe wizard asks 10-15 questions:\n\n```\n1. Deployment Mode?\n   a) Kubernetes (recommended for HA)\n   b) SSH (manual server management)\n   c) Docker Compose (hybrid local/remote)\n   → Your choice: a) Kubernetes\n\n2. Cloud Provider?\n   a) UpCloud\n   b) AWS\n   c) Hetzner\n   d) Local (self-managed servers)\n   → Your choice: a) UpCloud\n\n3. Workspace Name?\n   (names your infrastructure project)\n   → Your input: production-infrastructure\n\n4. Kubernetes Cluster?\n   a) Create new cluster\n   b) Use existing cluster\n   → Your choice: a) Create new\n\n5. Master Nodes Count? (1-5, default 3)\n   (for HA, recommend 3 or 5)\n   → Your input: 3\n\n6. Worker Nodes Count? (2-10, default 5)\n   (for scalability)\n   → Your input: 5\n\n7. Enable MFA?\n   (Multi-factor authentication for access)\n   → Your choice: y\n\n8. Enable Audit Logging?\n   (Log all operations for compliance)\n   → Your choice: y\n\n9. Storage Backend?\n   a) etcd (Kubernetes default)\n   b) PostgreSQL (external)\n   c) S3-compatible (cloud)\n   → Your choice: a) etcd\n\n10. Certificate Management?\n    a) Let's Encrypt (auto-renew)\n    b) Self-signed (for testing)\n    c) Bring your own\n    → Your choice: a) Let's Encrypt\n\n11. Monitoring?\n    a) Prometheus + Grafana\n    b) Datadog\n    c) CloudWatch\n    d) None (not recommended)\n    → Your choice: a) Prometheus + Grafana\n\n12. Logging?\n    a) ELK Stack\n    b) Splunk\n    c) CloudWatch Logs\n    d) None\n    → Your choice: a) ELK Stack\n\n13. Authorization?\n    a) Cedar policies (fine-grained)\n    b) RBAC (basic roles)\n    c) ABAC (attribute-based)\n    → Your choice: a) Cedar policies\n```\n\n#### Step 4: Configuration Generation\n\nCreates extensive Nickel configs:\n\n**platform/deployment.ncl**:\n```\n{\n  deployment = {\n    mode = 'kubernetes,\n    cluster_type = 'multi_master,\n    master_count = 3,\n    worker_count = 5,\n    ha_enabled = true,\n  },\n  security = {\n    mfa_enabled = true,\n    audit_logging = true,\n    tls_enabled = true,\n    certificate_provider = 'letsencrypt,\n  },\n  monitoring = {\n    prometheus_enabled = true,\n    grafana_enabled = true,\n  },\n  logging = {\n    elk_enabled = true,\n  },\n}\n| ProductionDeploymentConfig\n```\n\n**providers/upcloud.ncl**:\n```\n{\n  provider = 'upcloud,\n  api_key_ref = "rustyvault://secrets/upcloud/api-key",\n  api_secret_ref = "rustyvault://secrets/upcloud/api-secret",\n  region = "us-east-1",\n  server_template = "ubuntu-22.04",\n}\n| UpCloudProviderConfig\n```\n\n**cedar-policies/default.cedar**:\n```\npermit(\n  principal == User::"john@company.com",\n  action == Action::"Deploy",\n  resource == Workspace::"prod-infra"\n)\nwhen { principal.mfa_verified == true };\n\npermit(\n  principal in Group::"DevOps",\n  action == Action::"ReadMetrics",\n  resource in Team::"*"\n);\n\nforbid(\n  principal in Group::"Contractors",\n  action == Action::"DeleteWorkspace",\n  resource in Team::"*"\n);\n```\n\n#### Step 5: Validation\n\nAll configs validated:\n```\n✓ Validating system.ncl\n✓ Validating platform/deployment.ncl\n✓ Validating providers/upcloud.ncl\n✓ Validating cedar-policies/default.cedar\n✓ All configurations validated: PASSED\n```\n\n#### Step 6: Summary & Confirmation\n\n```\nSetup Summary\n─────────────────────────────────────────\nProfile:           Production\nDeployment Mode:   Kubernetes\nCloud Provider:    UpCloud\nMaster Nodes:      3\nWorker Nodes:      5\nMFA Enabled:       Yes\nAudit Logging:     Yes\nMonitoring:        Prometheus + Grafana\nLogging:           ELK Stack\n\nDo you want to proceed? (y/n): y\n```\n\n#### Step 7: Infrastructure Creation (Optional)\n\n```\nCreating UpCloud infrastructure...\n  Creating 3 master nodes... [networking configured]\n  Creating 5 worker nodes... [networking configured]\n  Deploying Kubernetes... [cluster bootstrap]\n  Installing monitoring... [Prometheus configured]\n  Installing logging... [ELK deployed]\n\nInfrastructure ready in ~12 minutes!\n\nKubernetes cluster access:\n  kubectl config use-context provisioning-prod-infra\n  kubectl cluster-info\n\nDeploy services:\n  kubectl apply -f infrastructure.ncl\n```\n\n### After Setup: Common Tasks\n\n**View Kubernetes cluster**:\n```\nkubectl get nodes\nkubectl get pods --all-namespaces\n```\n\n**Check Cedar authorization**:\n```\ncat ~/.config/provisioning/cedar-policies/default.cedar\n```\n\n**View infrastructure definition**:\n```\ncat workspace-production-infrastructure/infrastructure.ncl\n```\n\n**Deploy an application**:\n```\nprovisioning app deploy myapp --workspace production-infrastructure\n```\n\n**Monitor cluster**:\n```\n# Access Grafana\nopen http://localhost:3000\n\n# View Prometheus metrics\nopen http://localhost:9090\n```\n\n---\n\n## CI/CD Profile: Ephemeral Automated Setup\n\n### When to Use\n\n- **GitHub Actions workflows**: Test infrastructure changes\n- **GitLab CI pipelines**: Automated testing\n- **Jenkins jobs**: Integration testing\n- **Automated testing**: Spin up, test, cleanup\n- **Ephemeral environments**: No persistent state\n\n### What Gets Created\n\n**Config Files** (minimal Nickel):\n- `system.ncl` - CI environment info\n- `platform/deployment.ncl` - Minimal Docker Compose\n- `providers/local.ncl` - No credentials\n\n**Services**: Docker Compose (temporary)\n\n**Storage Location**: `/tmp/provisioning-ci-<job-id>/`\n\n### System Requirements\n\n**Minimal** (CI container):\n- OS: Any Linux\n- CPU: 1+ core\n- Memory: 2 GB RAM\n- Disk: 1 GB free\n\n**Dependencies**:\n- Nushell (0.109.0+)\n- Nickel (1.5.0+)\n- Docker or Podman\n\n### Step-by-Step Walkthrough\n\n#### Example: GitHub Actions\n\n```\nname: Integration Tests\n\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n\n      - name: Install Nushell\n        run: |\n          sudo apt-get update\n          sudo apt-get install -y nushell\n\n      - name: Install Nickel\n        run: |\n          sudo apt-get install -y nickel\n\n      - name: Install Provisioning\n        run: |\n          git clone https://github.com/project-provisioning/provisioning\n          cd provisioning\n          ./scripts/install.sh\n\n      - name: Setup Provisioning (CI/CD Profile)\n        run: |\n          export PROVISIONING_PROVIDER=local\n          export PROVISIONING_WORKSPACE=ci-test-${{ github.run_id }}\n          provisioning setup profile --profile cicd\n\n      - name: Run Integration Tests\n        run: |\n          # Services are now running\n          curl http://localhost:9090/health\n          curl http://localhost:3000/health\n\n          # Run your tests\n          ./tests/integration-test.sh\n\n      - name: Cleanup\n        if: always()\n        run: |\n          docker-compose down\n          # Automatic cleanup on job exit\n```\n\n#### What Happens\n\n**Step 1: Minimal Detection**\n```\n✓ Detected: CI environment\n✓ Profile: CICD\n```\n\n**Step 2: Ephemeral Config Creation**\n```\n✓ Created: /tmp/provisioning-ci-abc123def456/\n✓ Created: /tmp/provisioning-ci-abc123def456/system.ncl\n✓ Created: /tmp/provisioning-ci-abc123def456/platform/deployment.ncl\n```\n\n**Step 3: Validation**\n```\n✓ Validating system.ncl\n✓ Validating platform/deployment.ncl\n✓ All configurations validated: PASSED\n```\n\n**Step 4: Services Start**\n```\n✓ Starting Docker Compose services\n✓ Orchestrator running [port 9090]\n✓ Control Center running [port 3000]\n✓ KMS running [port 3001]\n✓ Services ready for tests\n```\n\n**Step 5: Tests Execute**\n```\n$ curl http://localhost:9090/health\n{"status": "healthy", "uptime": "2s"}\n\n$ ./tests/integration-test.sh\nTest: API endpoint... PASSED\nTest: Database schema... PASSED\nTest: Service discovery... PASSED\nAll tests passed!\n```\n\n**Step 6: Automatic Cleanup**\n```\n✓ Cleanup triggered (job exit)\n✓ Stopping Docker Compose\n✓ Removing temporary directory: /tmp/provisioning-ci-abc123def456/\n✓ Cleanup complete\n```\n\n### CI/CD Environment Variables\n\nUse environment variables to customize:\n\n```\n# Provider (local or cloud)\nexport PROVISIONING_PROVIDER=local|upcloud|aws|hetzner\n\n# Workspace name\nexport PROVISIONING_WORKSPACE=ci-test-${BUILD_ID}\n\n# Skip confirmations\nexport PROVISIONING_YES=true\n\n# Enable verbose output\nexport PROVISIONING_VERBOSE=true\n\n# Custom config location (if needed)\nexport PROVISIONING_CONFIG=/tmp/custom-config.ncl\n```\n\n### CI/CD Best Practices\n\n**1. Use matrix builds for testing**:\n```\nstrategy:\n  matrix:\n    profile: [developer, production]\n    provider: [local, aws]\n```\n\n**2. Cache Nickel compilation**:\n```\n- uses: actions/cache@v3\n  with:\n    path: ~/.cache/nickel\n    key: nickel-${{ hashFiles('*.ncl') }}\n```\n\n**3. Separate test stages**:\n```\n- name: Setup (CI/CD Profile)\n- name: Test Unit\n- name: Test Integration\n- name: Test E2E\n```\n\n**4. Publish test results**:\n```\n- name: Publish Test Results\n  if: always()\n  uses: actions/upload-artifact@v3\n  with:\n    name: test-results\n    path: test-results/\n```\n\n---\n\n## Profile Selection Guide\n\n### "Which profile should I choose?"\n\n**Start with Developer if**:\n- You're new to provisioning\n- You're testing locally\n- You want to understand how it works\n- You need quick feedback loops\n\n**Move to Production if**:\n- You're deploying to production\n- You need high availability\n- You have security requirements\n- You're managing a team\n- You need audit logging\n\n**Use CI/CD if**:\n- You're running automated tests\n- You're in a CI/CD pipeline\n- You want ephemeral environments\n- You don't need persistent state\n\n### Migration Path\n\n```\nDeveloper → Production\n  (ready for team)\n     ↓\n     └→ CI/CD (for testing)\n```\n\nYou can run Developer locally and CI/CD in your pipeline simultaneously.\n\n---\n\n## Modifying Profiles After Setup\n\n### Developer → Production Migration\n\nIf you started with Developer and want to move to Production:\n\n```\n# Backup your current setup\ntar czf provisioning-backup.tar.gz ~/.config/provisioning/\n\n# Run production setup\nprovisioning setup profile --profile production --interactive\n\n# Migrate any customizations from backup\ntar xzf provisioning-backup.tar.gz\n# Merge configs manually\n```\n\n### Customizing Profile Configs\n\nAll profiles' Nickel configs can be edited after setup:\n\n```\n# Edit deployment config\nvim ~/.config/provisioning/platform/deployment.ncl\n\n# Validate changes\nnickel typecheck ~/.config/provisioning/platform/deployment.ncl\n\n# Apply changes\ndocker-compose restart  # or kubectl apply -f\n```\n\n---\n\n## Troubleshooting Profile-Specific Issues\n\n### Developer Profile\n\n**Problem**: Docker not running\n```\n# Solution: Start Docker\ndocker daemon &\n# or\nsudo systemctl start docker\n```\n\n**Problem**: Ports 9090/3000/3001 already in use\n```\n# Solution: Kill conflicting process\nlsof -i :9090 | grep LISTEN | awk '{print $2}' | xargs kill -9\n```\n\n### Production Profile\n\n**Problem**: Kubernetes not installed\n```\n# Solution: Install kubectl\nbrew install kubectl  # macOS\nsudo apt-get install kubectl  # Linux\n```\n\n**Problem**: Cloud credentials rejected\n```\n# Solution: Verify credentials\nupcloud auth status  # or aws sts get-caller-identity\n# Re-run setup with correct credentials\n```\n\n### CI/CD Profile\n\n**Problem**: Services not accessible from test\n```\n# Solution: Use service DNS\ncurl http://orchestrator:9090/health  # instead of localhost\n```\n\n**Problem**: Cleanup not working\n```\n# Solution: Manual cleanup\ndocker system prune -f\nrm -rf /tmp/provisioning-ci-*/\n```\n\n---\n\n| **Next Step**: Choose your profile and run `provisioning setup profile --profile <developer | production | cicd>` |\n\n**Need more help?** See [Setup Guide](setup.md) or [Troubleshooting](../troubleshooting/troubleshooting.md)