provisioning/docs/src/getting-started/installation-guide.md

# Installation Guide

This guide will help you install Infrastructure Automation on your machine and get it ready for use.

## What You'll Learn

- System requirements and prerequisites
- Different installation methods
- How to verify your installation
- Setting up your environment
- Troubleshooting common installation issues

## System Requirements

### Operating System Support

- **Linux**: Any modern distribution (Ubuntu 20.04+, CentOS 8+, Debian 11+)
- **macOS**: 11.0+ (Big Sur and newer)
- **Windows**: Windows 10/11 with WSL2

### Hardware Requirements

| Component | Minimum | Recommended |
| ----------- | --------- | ------------- |
| CPU | 2 cores | 4+ cores |
| RAM | 4 GB | 8+ GB |
| Storage | 2 GB free | 10+ GB free |
| Network | Internet connection | Broadband connection |

### Architecture Support

- **x86_64** (Intel/AMD 64-bit) - Full support
- **ARM64** (Apple Silicon, ARM servers) - Full support

## Prerequisites

Before installation, ensure you have:

1. **Administrative privileges** - Required for system-wide installation
2. **Internet connection** - For downloading dependencies
3. **Terminal/Command line access** - Basic command line knowledge helpful

### Pre-installation Checklist

```bash
# Check your system
uname -a                    # View system information
df -h                      # Check available disk space
curl --version             # Verify internet connectivity
```

## Installation Methods

### Method 1: Package Installation (Recommended)

This is the easiest method for most users.

#### Step 1: Download the Package

```bash
# Download the latest release package
wget https://releases.example.com/provisioning-latest.tar.gz

# Or using curl
curl -LO https://releases.example.com/provisioning-latest.tar.gz
```

#### Step 2: Extract and Install

```bash
# Extract the package
tar xzf provisioning-latest.tar.gz

# Navigate to extracted directory
cd provisioning-*

# Run the installation script
sudo ./install-provisioning
```

The installer will:

- Install to `/usr/local/provisioning`
- Create a global command at `/usr/local/bin/provisioning`
- Install all required dependencies
- Set up configuration templates

### Method 2: Container Installation

For containerized environments or testing.

#### Using Docker

```bash
# Pull the provisioning container
docker pull provisioning:latest

# Create a container with persistent storage
docker run -it --name provisioning-setup 
  -v ~/provisioning-data:/data 
  provisioning:latest

# Install to host system (optional)
docker cp provisioning-setup:/usr/local/provisioning ./
sudo cp -r ./provisioning /usr/local/
sudo ln -sf /usr/local/provisioning/bin/provisioning /usr/local/bin/provisioning
```

#### Using Podman

```bash
# Similar to Docker but with Podman
podman pull provisioning:latest
podman run -it --name provisioning-setup 
  -v ~/provisioning-data:/data 
  provisioning:latest
```

### Method 3: Source Installation

For developers or custom installations.

#### Prerequisites for Source Installation

- **Git** - For cloning the repository
- **Build tools** - Compiler toolchain for your platform

#### Installation Steps

```bash
# Clone the repository
git clone https://github.com/your-org/provisioning.git
cd provisioning

# Run installation from source
./distro/from-repo.sh

# Or if you have development environment
./distro/pack-install.sh
```

### Method 4: Manual Installation

For advanced users who want complete control.

```bash
# Create installation directory
sudo mkdir -p /usr/local/provisioning

# Copy files (assumes you have the source)
sudo cp -r ./* /usr/local/provisioning/

# Create global command
sudo ln -sf /usr/local/provisioning/core/nulib/provisioning /usr/local/bin/provisioning

# Install dependencies manually
./install-dependencies.sh
```

## Installation Process Details

### What Gets Installed

The installation process sets up:

#### 1. Core System Files

```bash
/usr/local/provisioning/
├── core/                 # Core provisioning logic
├── providers/            # Cloud provider integrations
├── taskservs/           # Infrastructure services
├── cluster/             # Cluster configurations
├── schemas/             # Configuration schemas (Nickel)
├── templates/           # Template files
└── resources/           # Project resources
```

#### 2. Required Tools

| Tool | Version | Purpose |
| ------ | --------- | --------- |
| Nushell | 0.107.1 | Primary shell and scripting |
| Nickel | 1.15.0+ | Configuration language |
| SOPS | 3.10.2 | Secret management |
| Age | 1.2.1 | Encryption |
| K9s | 0.50.6 | Kubernetes management |

#### 3. Nushell Plugins

- **nu_plugin_tera** - Template rendering

#### 4. Configuration Files

- User configuration templates
- Environment-specific configs
- Default settings and schemas

## Post-Installation Verification

### Basic Verification

```bash
# Check if provisioning command is available
provisioning --version

# Verify installation
provisioning env

# Show comprehensive environment info
provisioning allenv
```

Expected output should show:

```bash
✅ Provisioning v1.0.0 installed
✅ All dependencies available
✅ Configuration loaded successfully
```

### Tool Verification

```bash
# Check individual tools
nu --version              # Should show Nushell 0.109.0+
nickel version            # Should show Nickel 1.5+
sops --version           # Should show SOPS 3.10.2
age --version            # Should show Age 1.2.1
k9s version              # Should show K9s 0.50.6
```

### Plugin Verification

```bash
# Start Nushell and check plugins
nu -c "version | get installed_plugins"

# Should include:
# - nu_plugin_tera (template rendering)
```

### Configuration Verification

```toml
# Validate configuration
provisioning validate config

# Should show:
# ✅ Configuration validation passed!
```

## Environment Setup

### Shell Configuration

Add to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.profile`):

```bash
# Add provisioning to PATH
export PATH="/usr/local/bin:$PATH"

# Optional: Set default provisioning directory
export PROVISIONING="/usr/local/provisioning"
```

### Configuration Initialization

```toml
# Initialize user configuration
provisioning init config

# This creates ~/.provisioning/config.user.toml
```

### First-Time Setup

```bash
# Set up your first workspace
mkdir -p ~/provisioning-workspace
cd ~/provisioning-workspace

# Initialize workspace
provisioning init config dev

# Verify setup
provisioning env
```

## Platform-Specific Instructions

### Linux (Ubuntu/Debian)

```bash
# Install system dependencies
sudo apt update
sudo apt install -y curl wget tar

# Proceed with standard installation
wget https://releases.example.com/provisioning-latest.tar.gz
tar xzf provisioning-latest.tar.gz
cd provisioning-*
sudo ./install-provisioning
```

### Linux (RHEL/CentOS/Fedora)

```bash
# Install system dependencies
sudo dnf install -y curl wget tar
# or for older versions: sudo yum install -y curl wget tar

# Proceed with standard installation
```

### macOS

```bash
# Using Homebrew (if available)
brew install curl wget

# Or download directly
curl -LO https://releases.example.com/provisioning-latest.tar.gz
tar xzf provisioning-latest.tar.gz
cd provisioning-*
sudo ./install-provisioning
```

### Windows (WSL2)

```bash
# In WSL2 terminal
sudo apt update
sudo apt install -y curl wget tar

# Proceed with Linux installation steps
wget https://releases.example.com/provisioning-latest.tar.gz
# ... continue as Linux
```

## Configuration Examples

### Basic Configuration

Create `~/.provisioning/config.user.toml`:

```toml
[core]
name = "my-provisioning"

[paths]
base = "/usr/local/provisioning"
infra = "~/provisioning-workspace"

[debug]
enabled = false
log_level = "info"

[providers]
default = "local"

[output]
format = "yaml"
```

### Development Configuration

For developers, use enhanced debugging:

```toml
[debug]
enabled = true
log_level = "debug"
check = true

[cache]
enabled = false  # Disable caching during development
```

## Upgrade and Migration

### Upgrading from Previous Version

```bash
# Backup current installation
sudo cp -r /usr/local/provisioning /usr/local/provisioning.backup

# Download new version
wget https://releases.example.com/provisioning-latest.tar.gz

# Extract and install
tar xzf provisioning-latest.tar.gz
cd provisioning-*
sudo ./install-provisioning

# Verify upgrade
provisioning --version
```

### Migrating Configuration

```toml
# Backup your configuration
cp -r ~/.provisioning ~/.provisioning.backup

# Initialize new configuration
provisioning init config

# Manually merge important settings from backup
```

## Troubleshooting Installation Issues

### Common Installation Problems

#### Permission Denied Errors

```bash
# Problem: Cannot write to /usr/local
# Solution: Use sudo
sudo ./install-provisioning

# Or install to user directory
./install-provisioning --prefix=$HOME/provisioning
export PATH="$HOME/provisioning/bin:$PATH"
```

#### Missing Dependencies

```bash
# Problem: curl/wget not found
# Ubuntu/Debian solution:
sudo apt install -y curl wget tar

# RHEL/CentOS solution:
sudo dnf install -y curl wget tar
```

#### Download Failures

```bash
# Problem: Cannot download package
# Solution: Check internet connection and try alternative
ping google.com

# Try alternative download method
curl -LO --retry 3 https://releases.example.com/provisioning-latest.tar.gz

# Or use wget with retries
wget --tries=3 https://releases.example.com/provisioning-latest.tar.gz
```

#### Extraction Failures

```bash
# Problem: Archive corrupted
# Solution: Verify and re-download
sha256sum provisioning-latest.tar.gz  # Check against published hash

# Re-download if hash doesn't match
rm provisioning-latest.tar.gz
wget https://releases.example.com/provisioning-latest.tar.gz
```

#### Tool Installation Failures

```bash
# Problem: Nushell installation fails
# Solution: Check architecture and OS compatibility
uname -m    # Should show x86_64 or arm64
uname -s    # Should show Linux, Darwin, etc.

# Try manual tool installation
./install-dependencies.sh --verbose
```

### Verification Failures

#### Command Not Found

```bash
# Problem: 'provisioning' command not found
# Check installation path
ls -la /usr/local/bin/provisioning

# If missing, create symlink
sudo ln -sf /usr/local/provisioning/core/nulib/provisioning /usr/local/bin/provisioning

# Add to PATH if needed
export PATH="/usr/local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
```

#### Plugin Errors

```bash
# Problem: Plugin command not found
# Solution: Ensure plugin is properly registered

# Check available plugins
nu -c "version | get installed_plugins"

# If plugin missing, reload Nushell:
exec nu
```

#### Configuration Errors

```toml
# Problem: Configuration validation fails
# Solution: Initialize with template
provisioning init config

# Or validate and show errors
provisioning validate config --detailed
```

### Getting Help

If you encounter issues not covered here:

1. **Check logs**: `provisioning --debug env`
2. **Validate configuration**: `provisioning validate config`
3. **Check system compatibility**: `provisioning version --verbose`
4. **Consult troubleshooting guide**: `docs/user/troubleshooting-guide.md`

## Next Steps

After successful installation:

1. **Complete the Getting Started Guide**: `docs/user/getting-started.md`
2. **Set up your first workspace**: `docs/user/workspace-setup.md`
3. **Learn about configuration**: `docs/user/configuration.md`
4. **Try example tutorials**: `docs/user/examples/`

Your provisioning is now ready to manage cloud infrastructure!