# Installation Validation & Bootstrap Guide\n\n**Objective**: Validate your provisioning installation, run bootstrap to initialize the workspace, and verify all components are working correctly.\n\n**Expected Duration**: 30-45 minutes\n\n**Prerequisites**: Fresh clone of provisioning repository at `/Users/Akasha/project-provisioning`\n\n---\n\n## Section 1: Prerequisites Verification\n\nBefore running the bootstrap script, verify that your system has all required dependencies.\n\n### Step 1.1: Check System Requirements\n\nRun these commands to verify your system meets minimum requirements:\n\n```\n# Check OS\nuname -s\n# Expected: Darwin (macOS), Linux, or WSL2\n\n# Check CPU cores\nsysctl -n hw.physicalcpu  # macOS\n# OR\nnproc  # Linux\n# Expected: 2 or more cores\n\n# Check RAM\nsysctl -n hw.memsize | awk '{print int($1 / 1024 / 1024 / 1024) " GB"}' # macOS\n# OR\ngrep MemTotal /proc/meminfo | awk '{print int($2 / 1024 / 1024) " GB"}'  # Linux\n# Expected: 2 GB or more (4 GB+ recommended)\n\n# Check free disk space\ndf -h | grep -E '^/dev|^Filesystem'\n# Expected: At least 2 GB free (10 GB+ recommended)\n```\n\n**Success Criteria**:\n- OS is macOS, Linux, or WSL2\n- CPU: 2+ cores available\n- RAM: 2 GB minimum, 4+ GB recommended\n- Disk: 2 GB free minimum\n\n### Step 1.2: Verify Nushell Installation\n\nNushell is required for bootstrap and CLI operations:\n\n```\ncommand -v nu\n# Expected output: /path/to/nu\n\nnu --version\n# Expected output: 0.109.0 or higher\n```\n\n**If Nushell is not installed:**\n\n```\n# macOS (using Homebrew)\nbrew install nushell\n\n# Linux (Debian/Ubuntu)\nsudo apt-get update && sudo apt-get install nushell\n\n# Linux (RHEL/CentOS)\nsudo yum install nushell\n\n# Or install from source: https://nushell.sh/book/installation.html\n```\n\n### Step 1.3: Verify Nickel Installation\n\nNickel is required for configuration validation:\n\n```\ncommand -v nickel\n# Expected output: /path/to/nickel\n\nnickel --version\n# Expected output: nickel 1.x.x or higher\n```\n\n**If Nickel is not installed:**\n\n```\n# Install via Cargo (requires Rust)\ncargo install nickel-lang-cli\n\n# Or: https://nickel-lang.org/\n```\n\n### Step 1.4: Verify Docker Installation\n\nDocker is required for running containerized services:\n\n```\ncommand -v docker\n# Expected output: /path/to/docker\n\ndocker --version\n# Expected output: Docker version 20.10 or higher\n```\n\n**If Docker is not installed:**\n\nVisit [Docker installation guide](https://docs.docker.com/get-docker/) and install for your OS.\n\n### Step 1.5: Check Provisioning Binary\n\nVerify the provisioning CLI binary exists:\n\n```\nls -la /Users/Akasha/project-provisioning/provisioning/core/cli/provisioning\n# Expected: -rwxr-xr-x (executable)\n\nfile /Users/Akasha/project-provisioning/provisioning/core/cli/provisioning\n# Expected: ELF 64-bit or similar binary format\n```\n\n**If binary is not executable:**\n\n```\nchmod +x /Users/Akasha/project-provisioning/provisioning/core/cli/provisioning\n```\n\n### Prerequisites Checklist\n\n```\n[ ] OS is macOS, Linux, or WSL2\n[ ] CPU: 2+ cores available\n[ ] RAM: 2 GB minimum installed\n[ ] Disk: 2+ GB free space\n[ ] Nushell 0.109.0+ installed\n[ ] Nickel 1.x.x installed\n[ ] Docker 20.10+ installed\n[ ] Provisioning binary exists and is executable\n```\n\n---\n\n## Section 2: Bootstrap Installation\n\nThe bootstrap script automates 7 stages of installation and initialization. Run it from the project root directory.\n\n### Step 2.1: Navigate to Project Root\n\n```\ncd /Users/Akasha/project-provisioning\n```\n\n### Step 2.2: Run Bootstrap Script\n\n```\n./provisioning/bootstrap/install.sh\n```\n\n### Bootstrap Output\n\nYou should see output similar to this:\n\n```\n╔════════════════════════════════════════════════════════════════╗\n║              PROVISIONING BOOTSTRAP (Bash)                     ║\n╚════════════════════════════════════════════════════════════════╝\n\n📊 Stage 1: System Detection\n─────────────────────────────────────────────────────────────────\n  OS: Darwin\n  Architecture: arm64 (or x86_64)\n  CPU Cores: 8\n  Memory: 16 GB\n  ✅ System requirements met\n\n📦 Stage 2: Checking Dependencies\n─────────────────────────────────────────────────────────────────\n  Versions:\n    Docker: Docker version 28.5.2\n    Rust: rustc 1.75.0\n    Nushell: 0.109.1\n  ✅ All dependencies found\n\n📁 Stage 3: Creating Directory Structure\n─────────────────────────────────────────────────────────────────\n  ✅ Directory structure created\n\n⚙️  Stage 4: Validating Configuration\n─────────────────────────────────────────────────────────────────\n  ✅ Configuration syntax valid\n\n📤 Stage 5: Exporting Configuration to TOML\n─────────────────────────────────────────────────────────────────\n  ✅ Configuration exported\n\n🚀 Stage 6: Initializing Orchestrator Service\n─────────────────────────────────────────────────────────────────\n  ✅ Orchestrator started\n\n✅ Stage 7: Verification\n─────────────────────────────────────────────────────────────────\n  ✅ All configuration files generated\n  ✅ All required directories created\n\n╔════════════════════════════════════════════════════════════════╗\n║                   BOOTSTRAP COMPLETE ✅                        ║\n╚════════════════════════════════════════════════════════════════╝\n\n📍 Next Steps:\n\n1. Verify configuration:\n   cat /Users/Akasha/project-provisioning/workspaces/workspace_librecloud/config/config.ncl\n\n2. Check orchestrator is running:\n   curl http://localhost:9090/health\n\n3. Start provisioning:\n   provisioning server create --infra sgoyol --name web-01\n```\n\n### What Bootstrap Does\n\nThe bootstrap script automatically:\n\n1. **Detects your system** (OS, CPU, RAM, architecture)\n2. **Verifies dependencies** (Docker, Rust, Nushell)\n3. **Creates workspace directories** (config, state, cache)\n4. **Validates Nickel configuration** (syntax checking)\n5. **Exports configuration** (Nickel → TOML files)\n6. **Initializes orchestrator** (starts service in background)\n7. **Verifies installation** (checks all files created)\n\n---\n\n## Section 3: Installation Validation\n\nAfter bootstrap completes, verify that all components are working correctly.\n\n### Step 3.1: Verify Workspace Directories\n\nBootstrap should have created workspace directories. Verify they exist:\n\n```\ncd /Users/Akasha/project-provisioning\n\n# Check all required directories\nls -la workspaces/workspace_librecloud/.orchestrator/data/queue/\nls -la workspaces/workspace_librecloud/.kms/\nls -la workspaces/workspace_librecloud/.providers/\nls -la workspaces/workspace_librecloud/.taskservs/\nls -la workspaces/workspace_librecloud/.clusters/\n```\n\n**Expected Output**:\n```\ntotal 0\ndrwxr-xr-x  2 user  group  64 Jan  7 10:30 .\n\n(directories exist and are accessible)\n```\n\n### Step 3.2: Verify Generated Configuration Files\n\nBootstrap should have exported Nickel configuration to TOML format:\n\n```\n# Check generated files exist\nls -la workspaces/workspace_librecloud/config/generated/\n\n# View workspace configuration\ncat workspaces/workspace_librecloud/config/generated/workspace.toml\n\n# View provider configuration\ncat workspaces/workspace_librecloud/config/generated/providers/upcloud.toml\n\n# View orchestrator configuration\ncat workspaces/workspace_librecloud/config/generated/platform/orchestrator.toml\n```\n\n**Expected Output**:\n```\nconfig/\n├── generated/\n│   ├── workspace.toml\n│   ├── providers/\n│   │   └── upcloud.toml\n│   └── platform/\n│       └── orchestrator.toml\n```\n\n### Step 3.3: Type-Check Nickel Configuration\n\nVerify Nickel configuration files have valid syntax:\n\n```\ncd /Users/Akasha/project-provisioning/workspaces/workspace_librecloud\n\n# Type-check main workspace config\nnickel typecheck config/config.ncl\n# Expected: No output (success) or clear error messages\n\n# Type-check infrastructure configs\nnickel typecheck infra/wuji/main.ncl\nnickel typecheck infra/sgoyol/main.ncl\n\n# Use workspace utility for comprehensive validation\nnu workspace.nu validate\n# Expected: ✓ All files validated successfully\n\n# Type-check all Nickel files\nnu workspace.nu typecheck\n```\n\n**Expected Output**:\n```\n✓ All files validated successfully\n✓ infra/wuji/main.ncl\n✓ infra/sgoyol/main.ncl\n```\n\n### Step 3.4: Verify Orchestrator Service\n\nThe orchestrator service manages workflows and deployments:\n\n```\n# Check if orchestrator is running (health check)\ncurl http://localhost:9090/health\n# Expected: {"status": "healthy"} or similar response\n\n# If health check fails, check orchestrator logs\ntail -f /Users/Akasha/project-provisioning/provisioning/platform/orchestrator/data/orchestrator.log\n\n# Alternative: Check if orchestrator process is running\nps aux | grep orchestrator\n# Expected: Running orchestrator process visible\n```\n\n**Expected Output**:\n```\n{\n  "status": "healthy",\n  "uptime": "0:05:23"\n}\n```\n\n**If Orchestrator Failed to Start:**\n\nCheck logs and restart manually:\n\n```\ncd /Users/Akasha/project-provisioning/provisioning/platform/orchestrator\n\n# Check log file\ncat data/orchestrator.log\n\n# Or start orchestrator manually\n./scripts/start-orchestrator.nu --background\n\n# Verify it's running\ncurl http://localhost:9090/health\n```\n\n### Step 3.5: Install Provisioning CLI (Optional)\n\nYou can install the provisioning CLI globally for easier access:\n\n```\n# Option A: System-wide installation (requires sudo)\ncd /Users/Akasha/project-provisioning\nsudo ./scripts/install-provisioning.sh\n\n# Verify installation\nprovisioning --version\nprovisioning help\n\n# Option B: Add to PATH temporarily (current session only)\nexport PATH="$PATH:/Users/Akasha/project-provisioning/provisioning/core/cli"\n\n# Verify\nprovisioning --version\n```\n\n**Expected Output**:\n```\nprovisioning version 1.0.0\n\nUsage: provisioning [OPTIONS] COMMAND\n\nCommands:\n  server     - Server management\n  workspace  - Workspace management\n  config     - Configuration management\n  help       - Show help information\n```\n\n### Installation Validation Checklist\n\n```\n[ ] Workspace directories created (.orchestrator, .kms, .providers, .taskservs, .clusters)\n[ ] Generated TOML files exist in config/generated/\n[ ] Nickel type-checking passes (no errors)\n[ ] Workspace utility validation passes\n[ ] Orchestrator responding to health check\n[ ] Orchestrator process running\n[ ] Provisioning CLI accessible and working\n```\n\n---\n\n## Section 4: Troubleshooting\n\nThis section covers common issues and solutions.\n\n### Issue: "Nushell not found"\n\n**Symptoms**:\n```\n./provisioning/bootstrap/install.sh: line X: nu: command not found\n```\n\n**Solution**:\n1. Install Nushell (see Step 1.2)\n2. Verify installation: `nu --version`\n3. Retry bootstrap script\n\n### Issue: "Nickel configuration validation failed"\n\n**Symptoms**:\n```\n⚙️  Stage 4: Validating Configuration\nError: Nickel configuration validation failed\n```\n\n**Solution**:\n1. Check Nickel syntax: `nickel typecheck config/config.ncl`\n2. Review error message for specific issue\n3. Edit config file: `vim config/config.ncl`\n4. Run bootstrap again\n\n### Issue: "Docker not installed"\n\n**Symptoms**:\n```\n❌ Docker is required but not installed\n```\n\n**Solution**:\n1. Install Docker: [Docker installation guide](https://docs.docker.com/get-docker/)\n2. Verify: `docker --version`\n3. Retry bootstrap script\n\n### Issue: "Configuration export failed"\n\n**Symptoms**:\n```\n⚠️ Configuration export encountered issues (may continue)\n```\n\n**Solution**:\n1. Check Nushell library paths: `nu -c "use provisioning/core/nulib/lib_provisioning/config/export.nu *"`\n2. Verify export library exists: `ls provisioning/core/nulib/lib_provisioning/config/export.nu`\n3. Re-export manually:\n   ```bash\n   cd /Users/Akasha/project-provisioning\n   nu -c "\n     use provisioning/core/nulib/lib_provisioning/config/export.nu *\n     export-all-configs 'workspaces/workspace_librecloud'\n   "\n   ```\n\n### Issue: "Orchestrator didn't start"\n\n**Symptoms**:\n```\n🚀 Stage 6: Initializing Orchestrator Service\n⚠️ Orchestrator may not have started (check logs)\n\ncurl http://localhost:9090/health\n# Connection refused\n```\n\n**Solution**:\n1. Check for port conflicts: `lsof -i :9090`\n2. If port 9090 is in use, either:\n   - Stop the conflicting service\n   - Change orchestrator port in configuration\n3. Check logs: `tail -f provisioning/platform/orchestrator/data/orchestrator.log`\n4. Start manually: `cd provisioning/platform/orchestrator && ./scripts/start-orchestrator.nu --background`\n5. Verify: `curl http://localhost:9090/health`\n\n### Issue: "Sudo password prompt during bootstrap"\n\n**Symptoms**:\n```\nStage 3: Creating Directory Structure\n[sudo] password for user:\n```\n\n**Solution**:\n- This is normal if creating directories in system locations\n- Enter your sudo password when prompted\n- Or: Run bootstrap from home directory instead\n\n### Issue: "Permission denied" on binary\n\n**Symptoms**:\n```\nbash: ./provisioning/bootstrap/install.sh: Permission denied\n```\n\n**Solution**:\n```\n# Make script executable\nchmod +x /Users/Akasha/project-provisioning/provisioning/bootstrap/install.sh\n\n# Retry\n./provisioning/bootstrap/install.sh\n```\n\n---\n\n## Section 5: Next Steps\n\nAfter successful installation validation, you can:\n\n### Option 1: Deploy workspace_librecloud\n\nTo deploy infrastructure to UpCloud:\n\n```\n# Read workspace deployment guide\ncat workspaces/workspace_librecloud/docs/deployment-guide.md\n\n# Or: From workspace directory\ncd workspaces/workspace_librecloud\ncat docs/deployment-guide.md\n```\n\n### Option 2: Create a New Workspace\n\nTo create a new workspace for different infrastructure:\n\n```\nprovisioning workspace init my_workspace --template minimal\n```\n\n### Option 3: Explore Available Modules\n\nDiscover what's available to deploy:\n\n```\n# List available task services\nprovisioning mod discover taskservs\n\n# List available providers\nprovisioning mod discover providers\n\n# List available clusters\nprovisioning mod discover clusters\n```\n\n---\n\n## Section 6: Verification Checklist\n\nAfter completing all steps, verify with this final checklist:\n\n```\nPrerequisites Verified:\n  [ ] OS is macOS, Linux, or WSL2\n  [ ] CPU: 2+ cores\n  [ ] RAM: 2+ GB available\n  [ ] Disk: 2+ GB free\n  [ ] Nushell 0.109.0+ installed\n  [ ] Nickel 1.x.x installed\n  [ ] Docker 20.10+ installed\n  [ ] Provisioning binary executable\n\nBootstrap Completed:\n  [ ] All 7 stages completed successfully\n  [ ] No error messages in output\n  [ ] Installation log shows success\n\nInstallation Validated:\n  [ ] Workspace directories exist\n  [ ] Generated TOML files exist\n  [ ] Nickel type-checking passes\n  [ ] Workspace validation passes\n  [ ] Orchestrator health check passes\n  [ ] Provisioning CLI works (if installed)\n\nReady to Deploy:\n  [ ] No errors in validation steps\n  [ ] All services responding correctly\n  [ ] Configuration properly exported\n```\n\n---\n\n## Getting Help\n\nIf you encounter issues not covered here:\n\n1. **Check logs**: `tail -f provisioning/platform/orchestrator/data/orchestrator.log`\n2. **Enable debug mode**: `provisioning --debug <command>`\n3. **Review bootstrap output**: Scroll up to see detailed error messages\n4. **Check documentation**: `provisioning help` or `provisioning guide <topic>`\n5. **Workspace guide**: `cat workspaces/workspace_librecloud/docs/deployment-guide.md`\n\n---\n\n## Summary\n\nThis guide covers:\n- ✅ Prerequisites verification (Nushell, Nickel, Docker)\n- ✅ Bootstrap installation (7-stage automated process)\n- ✅ Installation validation (directories, configs, services)\n- ✅ Troubleshooting common issues\n- ✅ Next steps for deployment\n\nYou now have a fully installed and validated provisioning system ready for workspace deployment.