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

# Installation

This guide walks you through installing the Provisioning Platform on your system.

## Overview

The installation process involves:

1. Cloning the repository
2. Installing Nushell plugins
3. Setting up configuration
4. Initializing your first workspace

Estimated time: 15-20 minutes

## Step 1: Clone the Repository

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

# Checkout the latest stable release (optional)
git checkout tags/v3.5.0
```

## Step 2: Install Nushell Plugins

The platform uses multiple Nushell plugins for enhanced functionality.

### Install nu_plugin_tera (Template Rendering)

```bash
# Install from crates.io
cargo install nu_plugin_tera

# Register with Nushell
nu -c "plugin add ~/.cargo/bin/nu_plugin_tera; plugin use tera"
```

### Verify Plugin Installation

```bash
# Start Nushell
nu

# List installed plugins
plugin list

# Expected output should include:
# - tera
```

## Step 3: Add CLI to PATH

Make the `provisioning` command available globally:

```bash
# Option 1: Symlink to /usr/local/bin (recommended)
sudo ln -s "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning

# Option 2: Add to PATH in your shell profile
echo 'export PATH="$PATH:'"$(pwd)"'/provisioning/core/cli"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or ~/.zshrc

# Verify installation
provisioning --version
```

## Step 4: Generate Age Encryption Keys

Generate keys for encrypting sensitive configuration:

```toml
# Create Age key directory
mkdir -p ~/.config/provisioning/age

# Generate private key
age-keygen -o ~/.config/provisioning/age/private_key.txt

# Extract public key
age-keygen -y ~/.config/provisioning/age/private_key.txt > ~/.config/provisioning/age/public_key.txt

# Secure the keys
chmod 600 ~/.config/provisioning/age/private_key.txt
chmod 644 ~/.config/provisioning/age/public_key.txt
```

## Step 5: Configure Environment

Set up basic environment variables:

```bash
# Create environment file
cat > ~/.provisioning/env << 'ENVEOF'
# Provisioning Environment Configuration
export PROVISIONING_ENV=dev
export PROVISIONING_PATH=$(pwd)
export PROVISIONING_KAGE=~/.config/provisioning/age
ENVEOF

# Source the environment
source ~/.provisioning/env

# Add to shell profile for persistence
echo 'source ~/.provisioning/env' >> ~/.bashrc  # or ~/.zshrc
```

## Step 6: Initialize Workspace

Create your first workspace:

```bash
# Initialize a new workspace
provisioning workspace init my-first-workspace

# Expected output:
# ✓ Workspace 'my-first-workspace' created successfully
# ✓ Configuration template generated
# ✓ Workspace activated

# Verify workspace
provisioning workspace list
```

## Step 7: Validate Installation

Run the installation verification:

```bash
# Check system configuration
provisioning validate config

# Check all dependencies
provisioning env

# View detailed environment
provisioning allenv
```

Expected output should show:

- ✅ All core dependencies installed
- ✅ Age keys configured
- ✅ Workspace initialized
- ✅ Configuration valid

## Optional: Install Platform Services

If you plan to use platform services (orchestrator, control center, etc.):

```bash
# Build platform services
cd provisioning/platform

# Build orchestrator
cd orchestrator
cargo build --release
cd ..

# Build control center
cd control-center
cargo build --release
cd ..

# Build KMS service
cd kms-service
cargo build --release
cd ..

# Verify builds
ls */target/release/
```

## Optional: Install Platform with Installer

Use the interactive installer for a guided setup:

```bash
# Build the installer
cd provisioning/platform/installer
cargo build --release

# Run interactive installer
./target/release/provisioning-installer

# Or headless installation
./target/release/provisioning-installer --headless --mode solo --yes
```

## Troubleshooting

### Nushell Plugin Not Found

If plugins aren't recognized:

```bash
# Rebuild plugin registry
nu -c "plugin list; plugin use tera"
```

### Permission Denied

If you encounter permission errors:

```bash
# Ensure proper ownership
sudo chown -R $USER:$USER ~/.config/provisioning

# Check PATH
echo $PATH | grep provisioning
```

### Age Keys Not Found

If encryption fails:

```bash
# Verify keys exist
ls -la ~/.config/provisioning/age/

# Regenerate if needed
age-keygen -o ~/.config/provisioning/age/private_key.txt
```

## Next Steps

Once installation is complete, proceed to:
→ **[First Deployment](03-first-deployment.md)**

## Additional Resources

- [Detailed Installation Guide](../user/installation-guide.md)
- [Workspace Management](../user/workspace-setup.md)
- [Troubleshooting Guide](../user/troubleshooting-guide.md)