# Installation

This guide covers installing the Provisioning platform on your system.

## Prerequisites

Ensure all [prerequisites](prerequisites.md) are met before proceeding.

## Installation Steps

### Step 1: Clone the Repository

```bash
# Clone the provisioning repository
git clone  [https://github.com/your-org/project-provisioning](https://github.com/your-org/project-provisioning)
cd project-provisioning
```

### Step 2: Add CLI to PATH

The CLI can be installed globally or run directly from the repository.

**Option A: Symbolic Link (Recommended)**:

```bash
# Create symbolic link to /usr/local/bin
ln -sf "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning

# Verify installation
provisioning version
```

**Option B: PATH Environment Variable**:

```bash
# Add to ~/.bashrc, ~/.zshrc, or ~/.config/nushell/env.nu
export PATH="$PATH:/path/to/project-provisioning/provisioning/core/cli"

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc
```

**Option C: Direct Execution**:

```bash
# Run directly from repository (no installation needed)
./provisioning/core/cli/provisioning version
```

### Step 3: Verify Installation

```bash
# Check CLI is accessible
provisioning version

# Show environment configuration
provisioning env

# Display help
provisioning help
```

Expected output:

```text
Provisioning Platform
CLI Version: (current version)
Nushell: 0.109.1+
Nickel: 1.15.1+
```

### Step 4: Initialize Configuration

Generate default configuration files:

```bash
# Create user configuration directory
mkdir -p ~/.config/provisioning

# Initialize default user configuration (optional)
provisioning config init
```

This creates `~/.config/provisioning/user_config.yaml` with sensible defaults.

### Step 5: Configure Cloud Provider Credentials

Configure credentials for at least one cloud provider.

**UpCloud**:

```yaml
# ~/.config/provisioning/user_config.yaml
providers:
  upcloud:
    username: "your-username"
    password: "your-password"  # Use SOPS for encryption in production
    default_zone: "de-fra1"
```

**AWS**:

```yaml
# ~/.config/provisioning/user_config.yaml
providers:
  aws:
    access_key_id: "AKIA..."
    secret_access_key: "..."  # Use SOPS for encryption in production
    default_region: "us-east-1"
```

**Local Provider** (no credentials required):

```yaml
# ~/.config/provisioning/user_config.yaml
providers:
  local:
    container_runtime: "docker"  # or "podman"
```

### Step 6: Encrypt Secrets (Recommended)

Use SOPS to encrypt sensitive configuration:

```bash
# Generate Age encryption key
age-keygen -o ~/.config/provisioning/age-key.txt

# Extract public key
export AGE_PUBLIC_KEY=$(grep "public key:" ~/.config/provisioning/age-key.txt | cut -d: -f2 | tr -d ' ')

# Create .sops.yaml configuration
cat > ~/.config/provisioning/.sops.yaml <<EOF
creation_rules:
  - path_regex: .*user_config\.yaml$
    age: $AGE_PUBLIC_KEY
EOF

# Encrypt configuration file
sops -e -i ~/.config/provisioning/user_config.yaml
```

**Decrypting** (automatic with SOPS):

```bash
# Set Age key path
export SOPS_AGE_KEY_FILE=~/.config/provisioning/age-key.txt

# SOPS will automatically decrypt when accessed
provisioning config show
```

### Step 7: Validate Configuration

```bash
# Validate all configuration files
provisioning validate config

# Check provider connectivity
provisioning providers

# Show complete environment
provisioning allenv
```

## Optional: Install Platform Services

Platform services provide additional capabilities like orchestration and web UI.

### Orchestrator Service (Rust)

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

# Start orchestrator
./target/release/orchestrator --port 5000
```

### Control Center (Web UI)

```bash
# Build control center
cd provisioning/platform/control-center
cargo build --release

# Start control center
./target/release/control-center --port 8080
```

### Native Plugins (Performance)

Install Nushell plugins for 10-50x performance improvements:

```bash
# Build and register plugins
cd provisioning/core/plugins

# Auth plugin
cargo build --release --package nu_plugin_auth
nu -c "register target/release/nu_plugin_auth"

# KMS plugin
cargo build --release --package nu_plugin_kms
nu -c "register target/release/nu_plugin_kms"

# Orchestrator plugin
cargo build --release --package nu_plugin_orchestrator
nu -c "register target/release/nu_plugin_orchestrator"

# Verify plugins are registered
nu -c "plugin list"
```

## Workspace Initialization

Create your first workspace for managing infrastructure:

```bash
# Initialize new workspace
provisioning workspace init my-project
cd my-project

# Verify workspace structure
ls -la
```

Expected workspace structure:

```text
my-project/
├── infra/          # Infrastructure Nickel schemas
├── config/         # Workspace configuration
├── extensions/     # Custom extensions
└── runtime/        # Runtime data and state
```

## Troubleshooting

### Common Issues

**CLI not found after installation**:

```bash
# Verify symlink was created
ls -l /usr/local/bin/provisioning

# Check PATH includes /usr/local/bin
echo $PATH

# Try direct path
/usr/local/bin/provisioning version
```

**Permission denied when creating symlink**:

```bash
# Use sudo for system-wide installation
sudo ln -sf "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning

# Or use user-local bin directory
mkdir -p ~/.local/bin
ln -sf "$(pwd)/provisioning/core/cli/provisioning" ~/.local/bin/provisioning
export PATH="$PATH:$HOME/.local/bin"
```

**Nushell version mismatch**:

```bash
# Check Nushell version
nu --version

# Update Nushell
brew upgrade nushell  # macOS
cargo install nu --force  # Linux
```

**Nickel not found**:

```bash
# Install Nickel
brew install nickel  # macOS
cargo install nickel-lang-cli  # Linux

# Verify
nickel --version
```

## Verification

Confirm successful installation:

```bash
# Complete installation check
provisioning version      # CLI version
provisioning env          # Environment configuration
provisioning providers    # Available cloud providers
provisioning validate config  # Configuration validation
provisioning help         # Help system
```

## Next Steps

Once installation is complete:

- [Quick Start](quick-start.md) - Deploy infrastructure in 5 minutes
- [First Deployment](first-deployment.md) - Comprehensive deployment walkthrough
- [Verification](verification.md) - Validate platform health
