# Installation\n\nThis guide walks you through installing the Provisioning Platform on your system.\n\n## Overview\n\nThe installation process involves:\n\n1. Cloning the repository\n2. Installing Nushell plugins\n3. Setting up configuration\n4. Initializing your first workspace\n\nEstimated time: 15-20 minutes\n\n## Step 1: Clone the Repository\n\n```\n# Clone the repository\ngit clone https://github.com/provisioning/provisioning-platform.git\ncd provisioning-platform\n\n# Checkout the latest stable release (optional)\ngit checkout tags/v3.5.0\n```\n\n## Step 2: Install Nushell Plugins\n\nThe platform uses multiple Nushell plugins for enhanced functionality.\n\n### Install nu_plugin_tera (Template Rendering)\n\n```\n# Install from crates.io\ncargo install nu_plugin_tera\n\n# Register with Nushell\nnu -c "plugin add ~/.cargo/bin/nu_plugin_tera; plugin use tera"\n```\n\n### Verify Plugin Installation\n\n```\n# Start Nushell\nnu\n\n# List installed plugins\nplugin list\n\n# Expected output should include:\n# - tera\n```\n\n## Step 3: Add CLI to PATH\n\nMake the `provisioning` command available globally:\n\n```\n# Option 1: Symlink to /usr/local/bin (recommended)\nsudo ln -s "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning\n\n# Option 2: Add to PATH in your shell profile\necho 'export PATH="$PATH:'"$(pwd)"'/provisioning/core/cli"' >> ~/.bashrc  # or ~/.zshrc\nsource ~/.bashrc  # or ~/.zshrc\n\n# Verify installation\nprovisioning --version\n```\n\n## Step 4: Generate Age Encryption Keys\n\nGenerate keys for encrypting sensitive configuration:\n\n```\n# Create Age key directory\nmkdir -p ~/.config/provisioning/age\n\n# Generate private key\nage-keygen -o ~/.config/provisioning/age/private_key.txt\n\n# Extract public key\nage-keygen -y ~/.config/provisioning/age/private_key.txt > ~/.config/provisioning/age/public_key.txt\n\n# Secure the keys\nchmod 600 ~/.config/provisioning/age/private_key.txt\nchmod 644 ~/.config/provisioning/age/public_key.txt\n```\n\n## Step 5: Configure Environment\n\nSet up basic environment variables:\n\n```\n# Create environment file\ncat > ~/.provisioning/env << 'ENVEOF'\n# Provisioning Environment Configuration\nexport PROVISIONING_ENV=dev\nexport PROVISIONING_PATH=$(pwd)\nexport PROVISIONING_KAGE=~/.config/provisioning/age\nENVEOF\n\n# Source the environment\nsource ~/.provisioning/env\n\n# Add to shell profile for persistence\necho 'source ~/.provisioning/env' >> ~/.bashrc  # or ~/.zshrc\n```\n\n## Step 6: Initialize Workspace\n\nCreate your first workspace:\n\n```\n# Initialize a new workspace\nprovisioning workspace init my-first-workspace\n\n# Expected output:\n# ✓ Workspace 'my-first-workspace' created successfully\n# ✓ Configuration template generated\n# ✓ Workspace activated\n\n# Verify workspace\nprovisioning workspace list\n```\n\n## Step 7: Validate Installation\n\nRun the installation verification:\n\n```\n# Check system configuration\nprovisioning validate config\n\n# Check all dependencies\nprovisioning env\n\n# View detailed environment\nprovisioning allenv\n```\n\nExpected output should show:\n\n- ✅ All core dependencies installed\n- ✅ Age keys configured\n- ✅ Workspace initialized\n- ✅ Configuration valid\n\n## Optional: Install Platform Services\n\nIf you plan to use platform services (orchestrator, control center, etc.):\n\n```\n# Build platform services\ncd provisioning/platform\n\n# Build orchestrator\ncd orchestrator\ncargo build --release\ncd ..\n\n# Build control center\ncd control-center\ncargo build --release\ncd ..\n\n# Build KMS service\ncd kms-service\ncargo build --release\ncd ..\n\n# Verify builds\nls */target/release/\n```\n\n## Optional: Install Platform with Installer\n\nUse the interactive installer for a guided setup:\n\n```\n# Build the installer\ncd provisioning/platform/installer\ncargo build --release\n\n# Run interactive installer\n./target/release/provisioning-installer\n\n# Or headless installation\n./target/release/provisioning-installer --headless --mode solo --yes\n```\n\n## Troubleshooting\n\n### Nushell Plugin Not Found\n\nIf plugins aren't recognized:\n\n```\n# Rebuild plugin registry\nnu -c "plugin list; plugin use tera"\n```\n\n### Permission Denied\n\nIf you encounter permission errors:\n\n```\n# Ensure proper ownership\nsudo chown -R $USER:$USER ~/.config/provisioning\n\n# Check PATH\necho $PATH | grep provisioning\n```\n\n### Age Keys Not Found\n\nIf encryption fails:\n\n```\n# Verify keys exist\nls -la ~/.config/provisioning/age/\n\n# Regenerate if needed\nage-keygen -o ~/.config/provisioning/age/private_key.txt\n```\n\n## Next Steps\n\nOnce installation is complete, proceed to:\n→ **[First Deployment](03-first-deployment.md)**\n\n## Additional Resources\n\n- [Detailed Installation Guide](../user/installation-guide.md)\n- [Workspace Management](../user/workspace-setup.md)\n- [Troubleshooting Guide](../user/troubleshooting-guide.md)
