# Unified Setup Guide\n\n**Quick Answer**: Run `provisioning setup profile` and choose your profile.\n\n---\n\n## Overview\n\nThe provisioning system uses a **unified profile-based setup** that creates type-safe configurations in your platform-specific home directory. No\nmatter which profile you choose, all configurations are validated with Nickel before use.\n\n### Three Setup Profiles\n\n|  | Profile | Duration | Use Case | Deployment | Security |  |\n|  | --------- | ---------- | ---------- | ----------- | ---------- |  |\n|  | **Developer** | <5 min | Local development, testing, learning | Docker Compose (local) | Minimal (local defaults) |  |\n|  | **Production** | ~12 min | Production-ready, HA, team deployments | Kubernetes or SSH | Full (MFA, audit, policies) |  |\n|  | **CI/CD** | <2 min | Automated pipelines, ephemeral setup | Docker Compose (temp) | CI secrets |  |\n\nAll profiles use **Nickel-first architecture**: configuration source of truth is type-safe Nickel, validated before use.\n\n---\n\n## Quick Start (Choose Your Profile)\n\n### Developer Profile (Recommended for First Time)\n\n```\n# Run unified setup\nprovisioning setup profile --profile developer\n\n# What happens:\n# 1. Detects your OS and system capabilities\n# 2. Creates Nickel configs in platform-specific location:\n#    • macOS: ~/Library/Application Support/provisioning/\n#    • Linux: ~/.config/provisioning/\n# 3. Validates all configs with Nickel typecheck\n# 4. Starts platform services (orchestrator, control-center, KMS)\n# 5. Verifies health checks\n\n# Verify it worked\ncurl http://localhost:9090/health\ncurl http://localhost:3000/health\ncurl http://localhost:3001/health\n```\n\nExpected output:\n```\n╔═════════════════════════════════════════════════════╗\n║   PROVISIONING SETUP - DEVELOPER PROFILE            ║\n╚═════════════════════════════════════════════════════╝\n\n✓ System detected: macOS (aarch64)\n✓ Docker available: Yes\n✓ Configuration location: ~/Library/Application Support/provisioning/\n✓ Config validation: PASSED (Nickel typecheck)\n✓ Services started: Orchestrator, Control Center, KMS\n✓ Health checks: All green\n\nSetup complete in ~4 minutes!\n```\n\n### Production Profile (HA, Security, Team Ready)\n\n```\n# Interactive setup for production\nprovisioning setup profile --profile production --interactive\n\n# What happens:\n# 1. Detects system: OS, CPU (≥4 required), memory (≥8GB recommended)\n# 2. Asks for deployment mode: Kubernetes (preferred) or SSH\n# 3. Asks for cloud provider: UpCloud, AWS, Hetzner, or local\n# 4. Asks for security settings: MFA, audit logging, Cedar policies\n# 5. Creates workspace infrastructure\n# 6. Creates Nickel configs with production overlays\n# 7. Validates all configs (Nickel typecheck)\n# 8. Optionally starts services\n\n# Setup with specific provider\nprovisioning setup profile --profile production --provider upcloud --interactive\n\n# Verify Nickel configs validated\nnickel typecheck ~/.config/provisioning/platform/deployment.ncl\n```\n\nExpected config structure:\n```\n~/.config/provisioning/\n├── system.ncl                    # System detection + capabilities\n├── user_preferences.ncl          # User settings (MFA, audit, etc.)\n├── platform/\n│   ├── deployment.ncl            # Deployment mode (kubernetes, ssh)\n│   └── services.ncl              # Service endpoints and timeouts\n├── providers/\n│   ├── upcloud.ncl               # UpCloud config (RustyVault refs)\n│   └── aws.ncl                   # AWS config (RustyVault refs)\n├── workspaces/\n│   └── infrastructure.ncl        # Infrastructure definitions\n└── cedar-policies/\n    └── default.cedar             # Authorization policies\n```\n\n### CI/CD Profile (Automated, Ephemeral)\n\n```\n# Fully automated setup for pipelines\nexport PROVISIONING_PROVIDER=local\nexport PROVISIONING_WORKSPACE=ci-test-${CI_JOB_ID}\n\nprovisioning setup profile --profile cicd\n\n# What happens:\n# 1. No interaction (reads from env vars)\n# 2. Creates ephemeral configs in /tmp/provisioning-ci-${CI_JOB_ID}/\n# 3. Validates with Nickel typecheck\n# 4. Starts Docker Compose services\n# 5. Registers cleanup hook (auto-cleanup on exit)\n\n# In your CI pipeline:\n# Services run, tests execute, cleanup automatic\n```\n\n---\n\n## Configuration Locations (Platform-Aware)\n\n### Linux (XDG Base Directory)\n\n```\n# Primary location\n~/.config/provisioning/\n\n# Or with XDG_CONFIG_HOME override\n$XDG_CONFIG_HOME/provisioning/\n\n# Files created during setup\n~/.config/provisioning/\n├── system.ncl                   # Source of truth (Nickel)\n├── user_preferences.ncl         # Source of truth (Nickel)\n├── platform/\n│   └── deployment.ncl           # Source of truth (Nickel)\n└── generated/                   # Optional: For services needing TOML\n    └── deployment.toml          # Auto-exported from deployment.ncl\n```\n\n### macOS (Application Support)\n\n```\n# Platform-specific location\n~/Library/Application Support/provisioning/\n\n# Same structure as Linux\n~/Library/Application Support/provisioning/\n├── system.ncl                   # Source of truth (Nickel)\n├── user_preferences.ncl         # Source of truth (Nickel)\n├── platform/\n│   └── deployment.ncl           # Source of truth (Nickel)\n└── generated/                   # Optional\n    └── deployment.toml\n```\n\n### Key Principle\n\n**Nickel is source of truth** - All `.ncl` files are authoritative, type-safe configurations validated by `nickel typecheck`. TOML files (if\ngenerated) are optional output only, never edited directly.\n\n---\n\n## What Happens During Setup\n\n### Step 1: System Detection\n\nProvisioning detects:\n- **OS**: macOS or Linux (Darwin detection)\n- **Architecture**: aarch64 or x86_64\n- **CPU Count**: Number of processors\n- **Memory**: Total system RAM in GB\n- **Disk Space**: Total available disk\n\n```\n# View detected system\nprovisioning setup detect --verbose\n```\n\n### Step 2: Profile Selection\n\nYou choose between:\n- **Developer**: Fast local setup, Docker Compose\n- **Production**: Full validation, Kubernetes/SSH, HA ready\n- **CI/CD**: Ephemeral, automated, no interaction\n\n### Step 3: Config Generation (Nickel-Based)\n\nSetup creates Nickel configs using composition:\n\n```\n# Example: system.ncl is composed from:\nlet helpers = import "../../schemas/platform/common/helpers.ncl"\nlet defaults = import "../../schemas/platform/defaults/system-defaults.ncl"\n\nhelpers.compose_config defaults {} {\n  os_name = 'macos,\n  cpu_count = 8,\n  memory_total_gb = 16,\n  setup_date = "2026-01-13T12:00:00Z"\n}\n| system_schema.SystemConfig  # Type contract validation\n```\n\nResult: **Type-safe config**, guaranteed valid structure and values.\n\n### Step 4: Validation (Mandatory)\n\nAll configs are validated:\n\n```\n# Done automatically during setup\nnickel typecheck ~/.config/provisioning/system.ncl\nnickel typecheck ~/.config/provisioning/platform/deployment.ncl\n\n# You can verify anytime\nnickel typecheck ~/.config/provisioning/**/*.ncl\n```\n\n### Step 5: Service Bootstrap (Profile-Dependent)\n\n**Developer**: Starts Docker Compose services locally\n```\ndocker-compose up -d orchestrator control-center kms\n```\n\n**Production**: Outputs Kubernetes manifests (doesn't auto-start, you review first)\n```\ncat ~/.config/provisioning/platform/deployment.ncl\n# Review, then deploy to your cluster\nkubectl apply -f generated-from-deployment.ncl\n```\n\n**CI/CD**: Starts ephemeral Docker Compose in `/tmp`\n```\n# Automatic cleanup on job exit\ndocker-compose -f /tmp/provisioning-ci-${JOB_ID}/compose.yml up\n# Tests run, cleanup automatic on script exit\n```\n\n---\n\n## Profile Comparison Details\n\n### Developer Profile\n\n**Goal**: Working provisioning system in less than 5 minutes, minimal configuration\n\n**What gets created**:\n- System config (auto-detected, no prompts)\n- User preferences (recommended defaults)\n- Docker Compose deployment (local mode)\n- Local provider (no credentials needed)\n\n**Security**:\n- All configs validated (Nickel typecheck)\n- Services use secure defaults\n- No external API keys needed\n- Passwords auto-generated and stored locally\n\n**Time**: 3-4 minutes\n\n**Example**:\n```\nprovisioning setup profile --profile developer\n\n# Output:\n# ✓ Detected: macOS, aarch64, 8 CPU, 16GB RAM\n# ✓ Created: ~/.config/provisioning/system.ncl\n# ✓ Created: ~/.config/provisioning/platform/deployment.ncl\n# ✓ Validated: All configs passed typecheck\n# ✓ Started: orchestrator (port 9090)\n# ✓ Started: control-center (port 3000)\n# ✓ Started: kms (port 3001)\n# ✓ Ready in 3 minutes 45 seconds\n```\n\n### Production Profile\n\n**Goal**: HA-ready, validated, secure deployment with full control\n\n**What gets created**:\n- System config (auto-detected)\n- User preferences (security-focused: MFA enabled, audit on)\n- Kubernetes or SSH deployment (your choice)\n- Cloud provider config (UpCloud, AWS, Hetzner, or local)\n- Workspace infrastructure (full IaC definitions)\n- Cedar authorization policies (fine-grained RBAC)\n\n**Security**:\n- All configs validated (Nickel typecheck)\n- Requires system minimums: 4+ CPU, 8+ GB RAM\n- MFA enabled by default (can configure)\n- Audit logging enabled (captures all operations)\n- Cedar policies for authorization\n- Credentials stored encrypted (RustyVault)\n\n**Time**: 10-15 minutes (interactive, many questions)\n\n**Example**:\n```\nprovisioning setup profile --profile production --interactive\n\n# Prompts:\n# Profile: Production ✓\n# Deployment mode? (kubernetes/ssh): kubernetes\n# Cloud provider? (upcloud/aws/hetzner/local): upcloud\n# Workspace name? my-prod-infra\n# Enable MFA? (y/n): y\n# Enable audit logging? (y/n): y\n# Number of master nodes? (1-5): 3\n# Worker node count? (2-10): 5\n\n# Output (15 minutes later):\n# ✓ Created: ~/.config/provisioning/system.ncl\n# ✓ Created: ~/.config/provisioning/platform/deployment.ncl\n# ✓ Created: ~/.config/provisioning/providers/upcloud.ncl\n# ✓ Created: workspace-prod-infra/infrastructure.ncl\n# ✓ Created: cedar-policies/default.cedar\n# ✓ Validated: All configs passed typecheck\n# ✓ Services NOT started (you'll deploy to cluster)\n# ✓ Ready for Kubernetes deployment\n```\n\n### CI/CD Profile\n\n**Goal**: Minimal setup, no interaction, auto-cleanup for pipelines\n\n**What gets created**:\n- System config (minimal, CI environment)\n- Deployment config (ephemeral, auto-cleanup)\n- Docker Compose (no Kubernetes overhead)\n- Runs in /tmp (temporary directory)\n\n**Security**:\n- All configs validated (Nickel typecheck)\n- No persistent state (by design)\n- Uses CI environment variables for secrets\n- Auto-cleanup on job completion\n- No credentials stored locally\n\n**Time**: Less than 2 minutes\n\n**Example**:\n```\n# In GitHub Actions:\n- name: Setup Provisioning\n  run: |\n    export PROVISIONING_PROVIDER=local\n    provisioning setup profile --profile cicd\n\n# Output:\n# ✓ Created: /tmp/provisioning-ci-abc123/\n# ✓ Validated: All configs passed typecheck\n# ✓ Started: Docker Compose services\n# ✓ Services ready for tests\n# Services will auto-cleanup on job exit\n```\n\n---\n\n## Verification\n\n### After Setup, Verify Everything Works\n\n**Developer Profile**:\n```\n# Check configs exist\nls -la ~/.config/provisioning/\nls -la ~/.config/provisioning/platform/\n\n# Verify Nickel validation\nnickel typecheck ~/.config/provisioning/system.ncl\nnickel typecheck ~/.config/provisioning/platform/deployment.ncl\n\n# Test services\ncurl http://localhost:9090/health\ncurl http://localhost:3000/health\ncurl http://localhost:3001/health\n\n# Expected: HTTP 200 with {"status": "healthy"}\n```\n\n**Production Profile**:\n```\n# Check Nickel configs\nnickel typecheck ~/.config/provisioning/system.ncl\nnickel typecheck ~/.config/provisioning/platform/deployment.ncl\nnickel typecheck ~/.config/provisioning/providers/upcloud.ncl\n\n# View deployment config\ncat ~/.config/provisioning/platform/deployment.ncl\n\n# View infrastructure definition\ncat workspace-my-prod-infra/infrastructure.ncl\n\n# View authorization policies\ncat ~/.config/provisioning/cedar-policies/default.cedar\n```\n\n**CI/CD Profile**:\n```\n# Check temp configs exist\nls -la /tmp/provisioning-ci-*/\n\n# Verify Nickel validation passed\nnickel typecheck /tmp/provisioning-ci-*/platform/deployment.ncl\n\n# Services should be running\ndocker ps | grep provisioning\n```\n\n---\n\n## Troubleshooting\n\n### Issue: "Nickel not found"\n\n**Cause**: Nickel binary not installed\n\n**Solution**:\n```\n# macOS\nbrew install nickel\n\n# Linux (Arch)\npacman -S nickel\n\n# From source\ngit clone https://github.com/nickel-lang/nickel\ncd nickel && cargo install --path .\n\n# Verify\nnickel --version  # Should be 1.5.0+\n```\n\n### Issue: "Configuration validation failed"\n\n**Cause**: Nickel typecheck error in generated config\n\n**Solution**:\n```\n# See detailed error\nnickel typecheck ~/.config/provisioning/platform/deployment.ncl --color always\n\n# Common issues:\n# - Missing required field (check schema)\n# - Wrong type (string vs number)\n# - Enum value not in allowed list\n\n# Delete and retry setup\nrm -rf ~/.config/provisioning/\nprovisioning setup profile --profile developer --verbose\n```\n\n### Issue: "Docker not available" (Developer Profile)\n\n**Cause**: Docker not installed or not running\n\n**Solution**:\n```\n# Check Docker\ndocker --version\ndocker ps\n\n# macOS: Install Docker Desktop\nbrew install --cask docker\n\n# Linux: Install Docker\nsudo apt-get install docker.io  # Ubuntu/Debian\nsudo pacman -S docker           # Arch\n\n# Start Docker\nsudo systemctl start docker\n\n# Retry setup\nprovisioning setup profile --profile developer\n```\n\n### Issue: "Services won't start"\n\n**Cause**: Port already in use, Docker not running, or resource constraints\n\n**Solution**:\n```\n# Check what's using ports 9090, 3000, 3001\nlsof -i :9090\nlsof -i :3000\nlsof -i :3001\n\n# Stop conflicting service or wait for it to release port\n\n# Stop and restart provisioning services\ndocker-compose down\ndocker-compose up -d\n\n# Check Docker resources\ndocker stats\ndocker system prune  # Free up space if needed\n```\n\n### Issue: "Permission denied" on config directory\n\n**Cause**: Directory created with wrong permissions\n\n**Solution**:\n```\n# Fix permissions (macOS)\nchmod 700 ~/Library/Application\ Support/provisioning/\n\n# Fix permissions (Linux)\nchmod 700 ~/.config/provisioning/\n\n# Fix nested directories\nchmod 700 ~/.config/provisioning/*\n\n# Retry setup\nprovisioning setup profile --profile developer\n```\n\n### Issue: "Wrong configuration being used"\n\n**Cause**: Services reading from old location or wrong environment variable\n\n**Solution**:\n```\n# Verify service sees new location\necho $PROVISIONING_CONFIG\n# Should be: ~/.config/provisioning/platform/deployment.ncl\n\n# Set explicitly if needed\nexport PROVISIONING_CONFIG=~/.config/provisioning/platform/deployment.ncl\nprovisioning service restart\n\n# Check what service is actually loading\nprovisioning service status --verbose\n```\n\n---\n\n## Using Workspace-Specific Overrides\n\nAfter initial setup, you can customize configs per workspace:\n\n```\n# Create workspace-specific override\nmkdir -p workspace-myproject/config\ncat > workspace-myproject/config/platform-overrides.ncl <<'EOF'\n{\n  orchestrator.server.port = 9999,\n  orchestrator.workspace.name = "myproject",\n  vault-service.storage.path = "./workspace-myproject/data/vault"\n}\nEOF\n\n# Services will merge this with the base config\nprovisioning workspace activate myproject\nprovisioning platform deploy  # Uses merged config\n```\n\n---\n\n## Next Steps\n\nAfter setup:\n\n1. **Create a Workspace**\n   ```bash\n   provisioning workspace create myapp\n   ```\n\n2. **Deploy Your First Service**\n   ```bash\n   provisioning service deploy nginx\n   ```\n\n3. **Configure Monitoring**\n   ```bash\n   provisioning monitor setup prometheus\n   ```\n\n4. **Set Up CI/CD Integration**\n   ```bash\n   provisioning ci configure github\n   ```\n\n5. **Learn Advanced Configuration**\n   - See: [Setup Profiles Guide](setup-profiles.md)\n   - See: [Platform Configuration](05-platform-configuration.md)\n   - See: [Nickel Configuration](../configuration/nickel-configuration.md)\n\n---\n\n## Key Concepts\n\n### Type-Safe Configuration (Nickel)\n\nAll configs use Nickel type contracts:\n- Field names and types enforced\n- Enum values validated\n- Invalid configs caught at nickel typecheck time\n- No runtime surprises\n\n### Platform-Specific Paths\n\nConfigs stored in platform-standard locations:\n- **Linux**: `~/.config/provisioning/` (XDG Base Directory)\n- **macOS**: `~/Library/Application Support/provisioning/`\n- Respects `$XDG_CONFIG_HOME` override on Linux\n\n### Composition Pattern\n\nConfigs built from:\n1. **Base defaults** (provisioning/schemas/platform/defaults/)\n2. **Profile overlay** (developer/production/cicd specific)\n3. **User customization** (optional, via Nickel import)\n\nResult: Minimal, validated, reproducible config.\n\n### Ephemeral vs. Persistent\n\n- **Developer/Production**: Persistent in home directory\n- **CI/CD**: Ephemeral in /tmp, auto-cleanup\n\n---\n\n## Getting Help\n\n```\n# Help for setup\nprovisioning setup --help\n\n# Help for profiles\nprovisioning setup profile --help\n\n# Interactive debugging\nprovisioning setup profile --profile developer --verbose\n\n# Validate configuration\nprovisioning setup validate\n\n# View detected capabilities\nprovisioning setup detect --verbose\n\n# Check platform status\nprovisioning platform status\n\n# View logs\nprovisioning service logs orchestrator\nprovisioning service logs control-center\nprovisioning service logs kms\n```\n\n---\n\n**Ready?** Run: `provisioning setup profile` and choose your profile!\n\n**Questions?** Check [Troubleshooting](../troubleshooting/troubleshooting.md) or [Setup Profiles Guide](setup-profiles.md)