# Prov-Ecosystem & Provctl Integrations - Quick Start Guide

**Date**: 2025-11-23
**Version**: 1.0.0
**For**: provisioning v3.6.0+

> Access powerful functionality from prov-ecosystem and provctl directly through provisioning CLI.

---

## Overview

Four integrated feature sets:

| Feature | Purpose | Best For |
|---------|---------|----------|
| **Runtime Abstraction** | Unified Docker/Podman/OrbStack/Colima/nerdctl | Multi-platform deployments |
| **SSH Advanced** | Pooling, circuit breaker, retry strategies | Large-scale distributed operations |
| **Backup System** | Multi-backend backups (Restic, Borg, Tar, Rsync) | Data protection & disaster recovery |
| **GitOps Events** | Event-driven deployments from Git | Continuous deployment automation |
| **Service Management** | Cross-platform services (systemd, launchd, runit) | Infrastructure service orchestration |

---

## Quick Start Commands

### 🏃 30-Second Test

```bash
# 1. Check what runtimes you have available
provisioning runtime list

# 2. Detect which runtime provisioning will use
provisioning runtime detect

# 3. Verify runtime works
provisioning runtime info
```plaintext

**Expected Output**:

```plaintext
Available runtimes:
  • docker
  • podman
```plaintext

---

## 1️⃣ Runtime Abstraction

### What It Does

Automatically detects and uses Docker, Podman, OrbStack, Colima, or nerdctl - whichever is available on your system. Eliminates hardcoding "docker" commands.

### Commands

```bash
# Detect available runtime
provisioning runtime detect
# Output: "Detected runtime: docker"

# Execute command in runtime
provisioning runtime exec "docker images"
# Runs: docker images

# Get runtime info
provisioning runtime info
# Shows: name, command, version

# List all available runtimes
provisioning runtime list
# Shows: docker, podman, orbstack...

# Adapt docker-compose for detected runtime
provisioning runtime compose ./docker-compose.yml
# Output: docker compose -f ./docker-compose.yml
```plaintext

### Examples

**Use Case 1: Works on macOS with OrbStack, Linux with Docker**

```bash
# User on macOS with OrbStack
$ provisioning runtime exec "docker run -it ubuntu bash"
# Automatically uses orbctl (OrbStack)

# User on Linux with Docker
$ provisioning runtime exec "docker run -it ubuntu bash"
# Automatically uses docker
```plaintext

**Use Case 2: Run docker-compose with detected runtime**

```bash
# Detect and run compose
$ compose_cmd=$(provisioning runtime compose ./docker-compose.yml)
$ eval $compose_cmd up -d
# Works with docker, podman, nerdctl automatically
```plaintext

### Configuration

No configuration needed! Runtime is auto-detected in order:

1. Docker (macOS: OrbStack first; Linux: Docker first)
2. Podman
3. OrbStack (macOS)
4. Colima (macOS)
5. nerdctl

---

## 2️⃣ SSH Advanced Operations

### What It Does

Advanced SSH with connection pooling (90% faster), circuit breaker for fault isolation, and deployment strategies (rolling, blue-green, canary).

### Commands

```bash
# Create SSH pool connection to host
provisioning ssh pool connect server.example.com root --port 22 --timeout 30

# Check pool status
provisioning ssh pool status

# List available deployment strategies
provisioning ssh strategies
# Output: rolling, blue-green, canary

# Configure retry strategy
provisioning ssh retry-config exponential --max-retries 3

# Check circuit breaker status
provisioning ssh circuit-breaker
# Output: state=closed, failures=0/5
```plaintext

### Deployment Strategies

| Strategy | Use Case | Risk |
|----------|----------|------|
| **Rolling** | Gradual rollout across hosts | Low (but slower) |
| **Blue-Green** | Zero-downtime, instant rollback | Very low |
| **Canary** | Test on small % before full rollout | Very low (5% at risk) |

### Example: Multi-Host Deployment

```bash
# Set up SSH pool
provisioning ssh pool connect srv01.example.com root
provisioning ssh pool connect srv02.example.com root
provisioning ssh pool connect srv03.example.com root

# Execute on pool (all 3 hosts in parallel)
provisioning ssh pool exec [srv01, srv02, srv03] "systemctl restart myapp" --strategy rolling

# Check status
provisioning ssh pool status
# Output: connections=3, active=0, idle=3, circuit_breaker=green
```plaintext

### Retry Strategies

```bash
# Exponential backoff: 100 ms, 200 ms, 400 ms, 800 ms...
provisioning ssh retry-config exponential --max-retries 5

# Linear backoff: 100 ms, 200 ms, 300 ms, 400 ms...
provisioning ssh retry-config linear --max-retries 3

# Fibonacci backoff: 100 ms, 100 ms, 200 ms, 300 ms, 500 ms...
provisioning ssh retry-config fibonacci --max-retries 4
```plaintext

---

## 3️⃣ Backup System

### What It Does

Multi-backend backup management with Restic, BorgBackup, Tar, or Rsync. Supports local, S3, SFTP, REST API, and Backblaze B2 repositories.

### Commands

```bash
# Create backup job
provisioning backup create daily-backup /data /var/lib \
  --backend restic \
  --repository s3://my-bucket/backups

# Restore from snapshot
provisioning backup restore snapshot-001 --restore_path /data

# List available snapshots
provisioning backup list

# Schedule regular backups
provisioning backup schedule daily-backup "0 2 * * *" \
  --paths ["/data" "/var/lib"] \
  --backend restic

# Show retention policy
provisioning backup retention
# Output: daily=7, weekly=4, monthly=12, yearly=5

# Check backup job status
provisioning backup status backup-job-001
```plaintext

### Backend Comparison

| Backend | Speed | Compression | Best For |
|---------|-------|-------------|----------|
| Restic | ⚡⚡⚡ | Excellent | Cloud backups |
| BorgBackup | ⚡⚡ | Excellent | Large archives |
| Tar | ⚡⚡⚡ | Good | Simple backups |
| Rsync | ⚡⚡⚡ | None | Incremental syncs |

### Example: Automated Daily Backups to S3

```bash
# Create backup configuration
provisioning backup create app-backup /opt/myapp /var/lib/myapp \
  --backend restic \
  --repository s3://prod-backups/myapp

# Schedule daily at 2 AM
provisioning backup schedule app-backup "0 2 * * *"

# Set retention: keep 7 days, 4 weeks, 12 months, 5 years
provisioning backup retention \
  --daily 7 \
  --weekly 4 \
  --monthly 12 \
  --yearly 5

# Verify backup was created
provisioning backup list
```plaintext

### Dry-Run (Test First)

```bash
# Test backup without actually creating it
provisioning backup create test-backup /data --check

# Test restore without actually restoring
provisioning backup restore snapshot-001 --check
```plaintext

---

## 4️⃣ GitOps Event-Driven Deployments

### What It Does

Automatically trigger deployments from Git events (push, PR, webhook, scheduled). Supports GitHub, GitLab, Gitea.

### Commands

```bash
# Load GitOps rules from configuration file
provisioning gitops rules ./gitops-rules.yaml

# Watch for Git events (starts webhook listener)
provisioning gitops watch --provider github --webhook-port 8080

# List supported events
provisioning gitops events
# Output: push, pull-request, webhook, scheduled, health-check, manual

# Manually trigger deployment
provisioning gitops trigger deploy-prod --environment prod

# List active deployments
provisioning gitops deployments --status running

# Show GitOps status
provisioning gitops status
# Output: active_rules=5, total=42, successful=40, failed=2
```plaintext

### Example: GitOps Configuration

**File: `gitops-rules.yaml`**

```yaml
rules:
  - name: deploy-prod
    provider: github
    repository: https://github.com/myorg/myrepo
    branch: main
    events:
      - push
    targets:
      - prod
    command: "provisioning deploy"
    require_approval: true

  - name: deploy-staging
    provider: github
    repository: https://github.com/myorg/myrepo
    branch: develop
    events:
      - push
      - pull-request
    targets:
      - staging
    command: "provisioning deploy"
    require_approval: false
```plaintext

**Then:**

```bash
# Load rules
provisioning gitops rules ./gitops-rules.yaml

# Watch for events
provisioning gitops watch --provider github

# When you push to main, deployment auto-triggers!
# git push origin main → provisioning deploy runs automatically
```plaintext

---

## 5️⃣ Service Management

### What It Does

Install, start, stop, and manage services across systemd (Linux), launchd (macOS), runit, and OpenRC.

### Commands

```bash
# Install service
provisioning service install myapp /usr/local/bin/myapp \
  --user myapp \
  --working-dir /opt/myapp

# Start service
provisioning service start myapp

# Stop service
provisioning service stop myapp

# Restart service
provisioning service restart myapp

# Check service status
provisioning service status myapp
# Output: running=true, uptime=86400s, restarts=2

# List all services
provisioning service list

# Detect init system
provisioning service detect-init
# Output: systemd (Linux), launchd (macOS), etc.
```plaintext

### Example: Install Custom Service

```bash
# On Linux (systemd)
provisioning service install provisioning-worker \
  /usr/local/bin/provisioning-worker \
  --user provisioning \
  --working-dir /opt/provisioning

# On macOS (launchd) - works the same!
provisioning service install provisioning-worker \
  /usr/local/bin/provisioning-worker \
  --user provisioning \
  --working-dir /opt/provisioning

# Service file is generated automatically for your platform
provisioning service start provisioning-worker
provisioning service status provisioning-worker
```plaintext

---

## 🎯 Common Workflows

### Workflow 1: Multi-Platform Deployment

```bash
# Works on macOS with OrbStack, Linux with Docker, etc.
provisioning runtime detect          # Detects your platform
provisioning runtime exec "docker ps" # Uses your runtime
```plaintext

### Workflow 2: Large-Scale SSH Operations

```bash
# Connect to multiple servers
for host in srv01 srv02 srv03; do
  provisioning ssh pool connect $host.example.com root
done

# Execute in parallel with 3x retry
provisioning ssh pool exec [srv01, srv02, srv03] \
  "systemctl restart app" \
  --strategy rolling \
  --retry exponential
```plaintext

### Workflow 3: Automated Backups

```bash
# Create backup job
provisioning backup create daily /opt/app /data \
  --backend restic \
  --repository s3://backups

# Schedule for 2 AM every day
provisioning backup schedule daily "0 2 * * *"

# Verify it works
provisioning backup list
```plaintext

### Workflow 4: Continuous Deployment from Git

```bash
# Define rules in YAML
cat > gitops-rules.yaml << 'EOF'
rules:
  - name: deploy-prod
    provider: github
    repository: https://github.com/myorg/repo
    branch: main
    events: [push]
    targets: [prod]
    command: "provisioning deploy"
EOF

# Load and activate
provisioning gitops rules ./gitops-rules.yaml
provisioning gitops watch --provider github

# Now pushing to main auto-deploys!
```plaintext

---

## 🔧 Advanced Configuration

### Using with Nickel Configuration

All integrations support Nickel schemas for advanced configuration:

```nickel
let { IntegrationConfig } = import "provisioning/integrations.ncl" in
{
  integrations = {
    # Runtime configuration
    runtime = {
      preferred = "podman",
      check_order = ["podman", "docker", "nerdctl"],
      timeout_secs = 5,
      enable_cache = true,
    },

    # Backup with retention policy
    backup = {
      default_backend = "restic",
      default_repository = {
        type = "s3",
        bucket = "prod-backups",
        prefix = "daily",
      },
      jobs = [],
      verify_after_backup = true,
    },

    # GitOps rules with approval
    gitops = {
      rules = [],
      default_strategy = "blue-green",
      dry_run_by_default = false,
      enable_audit_log = true,
    },
  }
}
```plaintext

---

## 💡 Tips & Tricks

### Tip 1: Dry-Run Mode

All major operations support `--check` for testing:

```bash
provisioning runtime exec "systemctl restart app" --check
# Output: Would execute: [docker exec ...]

provisioning backup create test /data --check
# Output: Backup would be created: [test]

provisioning gitops trigger deploy-test --check
# Output: Deployment would trigger
```plaintext

### Tip 2: Output Formats

Some commands support JSON output:

```bash
provisioning runtime list --out json
provisioning backup list --out json
provisioning gitops deployments --out json
```plaintext

### Tip 3: Integration with Scripts

Chain commands in shell scripts:

```bash
#!/bin/bash

# Detect runtime and use it
RUNTIME=$(provisioning runtime detect | grep -oP 'docker|podman|nerdctl')

# Execute using detected runtime
provisioning runtime exec "docker ps"

# Create backup before deploy
provisioning backup create pre-deploy-$(date +%s) /opt/app

# Deploy
provisioning deploy

# Verify with GitOps
provisioning gitops status
```plaintext

---

## 🐛 Troubleshooting

### Problem: "No container runtime detected"

**Solution**: Install Docker, Podman, or OrbStack:

```bash
# macOS
brew install orbstack

# Linux
sudo apt-get install docker.io

# Then verify
provisioning runtime detect
```plaintext

### Problem: SSH connection timeout

**Solution**: Check port and timeout settings:

```bash
# Use different port
provisioning ssh pool connect server.example.com root --port 2222

# Increase timeout
provisioning ssh pool connect server.example.com root --timeout 60
```plaintext

### Problem: Backup fails with "Permission denied"

**Solution**: Check permissions on backup path:

```bash
# Check if user can read target paths
ls -l /data  # Should be readable

# Run with elevated privileges if needed
sudo provisioning backup create mybak /data --backend restic
```plaintext

---

## 📚 Learn More

| Topic | Location |
|-------|----------|
| Architecture | `docs/architecture/ECOSYSTEM_INTEGRATION.md` |
| CLI Help | `provisioning help integrations` |
| Rust Bridge | `provisioning/platform/integrations/provisioning-bridge/` |
| Nushell Modules | `provisioning/core/nulib/lib_provisioning/integrations/` |
| Nickel Schemas | `provisioning/schemas/integrations/` |

---

## 🆘 Need Help

```bash
# General help
provisioning help integrations

# Specific command help
provisioning runtime --help
provisioning backup --help
provisioning gitops --help

# System diagnostics
provisioning status
provisioning health
```plaintext

---

**Last Updated**: 2025-11-23
**Version**: 1.0.0
