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

# 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

# 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

# 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

# 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

# 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

# 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.

# 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

/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

# Check if provisioning command is available
provisioning --version

# Verify installation
provisioning env

# Show comprehensive environment info
provisioning allenv

Expected output should show:

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

Tool Verification

# 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

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

# Should include:
# - nu_plugin_tera (template rendering)

Configuration Verification

# Validate configuration
provisioning validate config

# Should show:
# ✅ Configuration validation passed!

Environment Setup

Shell Configuration

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

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

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

Configuration Initialization

# Initialize user configuration
provisioning init config

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

First-Time Setup

# 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)

# 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)

# 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

# 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)

# 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:

[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:

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

[cache]
enabled = false  # Disable caching during development

Upgrade and Migration

Upgrading from Previous Version

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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!