# Installation Guide\n\nThis guide will help you install Infrastructure Automation on your machine and get it ready for use.\n\n## What You'll Learn\n\n- System requirements and prerequisites\n- Different installation methods\n- How to verify your installation\n- Setting up your environment\n- Troubleshooting common installation issues\n\n## System Requirements\n\n### Operating System Support\n\n- **Linux**: Any modern distribution (Ubuntu 20.04+, CentOS 8+, Debian 11+)\n- **macOS**: 11.0+ (Big Sur and newer)\n- **Windows**: Windows 10/11 with WSL2\n\n### Hardware Requirements\n\n| Component | Minimum | Recommended |\n| ----------- | --------- | ------------- |\n| CPU | 2 cores | 4+ cores |\n| RAM | 4 GB | 8+ GB |\n| Storage | 2 GB free | 10+ GB free |\n| Network | Internet connection | Broadband connection |\n\n### Architecture Support\n\n- **x86_64** (Intel/AMD 64-bit) - Full support\n- **ARM64** (Apple Silicon, ARM servers) - Full support\n\n## Prerequisites\n\nBefore installation, ensure you have:\n\n1. **Administrative privileges** - Required for system-wide installation\n2. **Internet connection** - For downloading dependencies\n3. **Terminal/Command line access** - Basic command line knowledge helpful\n\n### Pre-installation Checklist\n\n```\n# Check your system\nuname -a                    # View system information\ndf -h                      # Check available disk space\ncurl --version             # Verify internet connectivity\n```\n\n## Installation Methods\n\n### Method 1: Package Installation (Recommended)\n\nThis is the easiest method for most users.\n\n#### Step 1: Download the Package\n\n```\n# Download the latest release package\nwget https://releases.example.com/provisioning-latest.tar.gz\n\n# Or using curl\ncurl -LO https://releases.example.com/provisioning-latest.tar.gz\n```\n\n#### Step 2: Extract and Install\n\n```\n# Extract the package\ntar xzf provisioning-latest.tar.gz\n\n# Navigate to extracted directory\ncd provisioning-*\n\n# Run the installation script\nsudo ./install-provisioning\n```\n\nThe installer will:\n\n- Install to `/usr/local/provisioning`\n- Create a global command at `/usr/local/bin/provisioning`\n- Install all required dependencies\n- Set up configuration templates\n\n### Method 2: Container Installation\n\nFor containerized environments or testing.\n\n#### Using Docker\n\n```\n# Pull the provisioning container\ndocker pull provisioning:latest\n\n# Create a container with persistent storage\ndocker run -it --name provisioning-setup \\n  -v ~/provisioning-data:/data \\n  provisioning:latest\n\n# Install to host system (optional)\ndocker cp provisioning-setup:/usr/local/provisioning ./\nsudo cp -r ./provisioning /usr/local/\nsudo ln -sf /usr/local/provisioning/bin/provisioning /usr/local/bin/provisioning\n```\n\n#### Using Podman\n\n```\n# Similar to Docker but with Podman\npodman pull provisioning:latest\npodman run -it --name provisioning-setup \\n  -v ~/provisioning-data:/data \\n  provisioning:latest\n```\n\n### Method 3: Source Installation\n\nFor developers or custom installations.\n\n#### Prerequisites for Source Installation\n\n- **Git** - For cloning the repository\n- **Build tools** - Compiler toolchain for your platform\n\n#### Installation Steps\n\n```\n# Clone the repository\ngit clone https://github.com/your-org/provisioning.git\ncd provisioning\n\n# Run installation from source\n./distro/from-repo.sh\n\n# Or if you have development environment\n./distro/pack-install.sh\n```\n\n### Method 4: Manual Installation\n\nFor advanced users who want complete control.\n\n```\n# Create installation directory\nsudo mkdir -p /usr/local/provisioning\n\n# Copy files (assumes you have the source)\nsudo cp -r ./* /usr/local/provisioning/\n\n# Create global command\nsudo ln -sf /usr/local/provisioning/core/nulib/provisioning /usr/local/bin/provisioning\n\n# Install dependencies manually\n./install-dependencies.sh\n```\n\n## Installation Process Details\n\n### What Gets Installed\n\nThe installation process sets up:\n\n#### 1. Core System Files\n\n```\n/usr/local/provisioning/\n├── core/                 # Core provisioning logic\n├── providers/            # Cloud provider integrations\n├── taskservs/           # Infrastructure services\n├── cluster/             # Cluster configurations\n├── schemas/             # Configuration schemas (Nickel)\n├── templates/           # Template files\n└── resources/           # Project resources\n```\n\n#### 2. Required Tools\n\n| Tool | Version | Purpose |\n| ------ | --------- | --------- |\n| Nushell | 0.107.1 | Primary shell and scripting |\n| Nickel | 1.15.0+ | Configuration language |\n| SOPS | 3.10.2 | Secret management |\n| Age | 1.2.1 | Encryption |\n| K9s | 0.50.6 | Kubernetes management |\n\n#### 3. Nushell Plugins\n\n- **nu_plugin_tera** - Template rendering\n\n#### 4. Configuration Files\n\n- User configuration templates\n- Environment-specific configs\n- Default settings and schemas\n\n## Post-Installation Verification\n\n### Basic Verification\n\n```\n# Check if provisioning command is available\nprovisioning --version\n\n# Verify installation\nprovisioning env\n\n# Show comprehensive environment info\nprovisioning allenv\n```\n\nExpected output should show:\n\n```\n✅ Provisioning v1.0.0 installed\n✅ All dependencies available\n✅ Configuration loaded successfully\n```\n\n### Tool Verification\n\n```\n# Check individual tools\nnu --version              # Should show Nushell 0.109.0+\nnickel version            # Should show Nickel 1.5+\nsops --version           # Should show SOPS 3.10.2\nage --version            # Should show Age 1.2.1\nk9s version              # Should show K9s 0.50.6\n```\n\n### Plugin Verification\n\n```\n# Start Nushell and check plugins\nnu -c "version | get installed_plugins"\n\n# Should include:\n# - nu_plugin_tera (template rendering)\n```\n\n### Configuration Verification\n\n```\n# Validate configuration\nprovisioning validate config\n\n# Should show:\n# ✅ Configuration validation passed!\n```\n\n## Environment Setup\n\n### Shell Configuration\n\nAdd to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.profile`):\n\n```\n# Add provisioning to PATH\nexport PATH="/usr/local/bin:$PATH"\n\n# Optional: Set default provisioning directory\nexport PROVISIONING="/usr/local/provisioning"\n```\n\n### Configuration Initialization\n\n```\n# Initialize user configuration\nprovisioning init config\n\n# This creates ~/.provisioning/config.user.toml\n```\n\n### First-Time Setup\n\n```\n# Set up your first workspace\nmkdir -p ~/provisioning-workspace\ncd ~/provisioning-workspace\n\n# Initialize workspace\nprovisioning init config dev\n\n# Verify setup\nprovisioning env\n```\n\n## Platform-Specific Instructions\n\n### Linux (Ubuntu/Debian)\n\n```\n# Install system dependencies\nsudo apt update\nsudo apt install -y curl wget tar\n\n# Proceed with standard installation\nwget https://releases.example.com/provisioning-latest.tar.gz\ntar xzf provisioning-latest.tar.gz\ncd provisioning-*\nsudo ./install-provisioning\n```\n\n### Linux (RHEL/CentOS/Fedora)\n\n```\n# Install system dependencies\nsudo dnf install -y curl wget tar\n# or for older versions: sudo yum install -y curl wget tar\n\n# Proceed with standard installation\n```\n\n### macOS\n\n```\n# Using Homebrew (if available)\nbrew install curl wget\n\n# Or download directly\ncurl -LO https://releases.example.com/provisioning-latest.tar.gz\ntar xzf provisioning-latest.tar.gz\ncd provisioning-*\nsudo ./install-provisioning\n```\n\n### Windows (WSL2)\n\n```\n# In WSL2 terminal\nsudo apt update\nsudo apt install -y curl wget tar\n\n# Proceed with Linux installation steps\nwget https://releases.example.com/provisioning-latest.tar.gz\n# ... continue as Linux\n```\n\n## Configuration Examples\n\n### Basic Configuration\n\nCreate `~/.provisioning/config.user.toml`:\n\n```\n[core]\nname = "my-provisioning"\n\n[paths]\nbase = "/usr/local/provisioning"\ninfra = "~/provisioning-workspace"\n\n[debug]\nenabled = false\nlog_level = "info"\n\n[providers]\ndefault = "local"\n\n[output]\nformat = "yaml"\n```\n\n### Development Configuration\n\nFor developers, use enhanced debugging:\n\n```\n[debug]\nenabled = true\nlog_level = "debug"\ncheck = true\n\n[cache]\nenabled = false  # Disable caching during development\n```\n\n## Upgrade and Migration\n\n### Upgrading from Previous Version\n\n```\n# Backup current installation\nsudo cp -r /usr/local/provisioning /usr/local/provisioning.backup\n\n# Download new version\nwget https://releases.example.com/provisioning-latest.tar.gz\n\n# Extract and install\ntar xzf provisioning-latest.tar.gz\ncd provisioning-*\nsudo ./install-provisioning\n\n# Verify upgrade\nprovisioning --version\n```\n\n### Migrating Configuration\n\n```\n# Backup your configuration\ncp -r ~/.provisioning ~/.provisioning.backup\n\n# Initialize new configuration\nprovisioning init config\n\n# Manually merge important settings from backup\n```\n\n## Troubleshooting Installation Issues\n\n### Common Installation Problems\n\n#### Permission Denied Errors\n\n```\n# Problem: Cannot write to /usr/local\n# Solution: Use sudo\nsudo ./install-provisioning\n\n# Or install to user directory\n./install-provisioning --prefix=$HOME/provisioning\nexport PATH="$HOME/provisioning/bin:$PATH"\n```\n\n#### Missing Dependencies\n\n```\n# Problem: curl/wget not found\n# Ubuntu/Debian solution:\nsudo apt install -y curl wget tar\n\n# RHEL/CentOS solution:\nsudo dnf install -y curl wget tar\n```\n\n#### Download Failures\n\n```\n# Problem: Cannot download package\n# Solution: Check internet connection and try alternative\nping google.com\n\n# Try alternative download method\ncurl -LO --retry 3 https://releases.example.com/provisioning-latest.tar.gz\n\n# Or use wget with retries\nwget --tries=3 https://releases.example.com/provisioning-latest.tar.gz\n```\n\n#### Extraction Failures\n\n```\n# Problem: Archive corrupted\n# Solution: Verify and re-download\nsha256sum provisioning-latest.tar.gz  # Check against published hash\n\n# Re-download if hash doesn't match\nrm provisioning-latest.tar.gz\nwget https://releases.example.com/provisioning-latest.tar.gz\n```\n\n#### Tool Installation Failures\n\n```\n# Problem: Nushell installation fails\n# Solution: Check architecture and OS compatibility\nuname -m    # Should show x86_64 or arm64\nuname -s    # Should show Linux, Darwin, etc.\n\n# Try manual tool installation\n./install-dependencies.sh --verbose\n```\n\n### Verification Failures\n\n#### Command Not Found\n\n```\n# Problem: 'provisioning' command not found\n# Check installation path\nls -la /usr/local/bin/provisioning\n\n# If missing, create symlink\nsudo ln -sf /usr/local/provisioning/core/nulib/provisioning /usr/local/bin/provisioning\n\n# Add to PATH if needed\nexport PATH="/usr/local/bin:$PATH"\necho 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc\n```\n\n#### Plugin Errors\n\n```\n# Problem: Plugin command not found\n# Solution: Ensure plugin is properly registered\n\n# Check available plugins\nnu -c "version | get installed_plugins"\n\n# If plugin missing, reload Nushell:\nexec nu\n```\n\n#### Configuration Errors\n\n```\n# Problem: Configuration validation fails\n# Solution: Initialize with template\nprovisioning init config\n\n# Or validate and show errors\nprovisioning validate config --detailed\n```\n\n### Getting Help\n\nIf you encounter issues not covered here:\n\n1. **Check logs**: `provisioning --debug env`\n2. **Validate configuration**: `provisioning validate config`\n3. **Check system compatibility**: `provisioning version --verbose`\n4. **Consult troubleshooting guide**: `docs/user/troubleshooting-guide.md`\n\n## Next Steps\n\nAfter successful installation:\n\n1. **Complete the Getting Started Guide**: `docs/user/getting-started.md`\n2. **Set up your first workspace**: `docs/user/workspace-setup.md`\n3. **Learn about configuration**: `docs/user/configuration.md`\n4. **Try example tutorials**: `docs/user/examples/`\n\nYour provisioning is now ready to manage cloud infrastructure!