# Prov-Ecosystem & Provctl Integrations - Quick Start Guide\n\n**Date**: 2025-11-23\n**Version**: 1.0.0\n**For**: provisioning v3.6.0+\n\n> Access powerful functionality from prov-ecosystem and provctl directly through provisioning CLI.\n\n---\n\n## Overview\n\nFour integrated feature sets:\n\n| Feature | Purpose | Best For |\n| --------- | --------- | ---------- |\n| **Runtime Abstraction** | Unified Docker/Podman/OrbStack/Colima/nerdctl | Multi-platform deployments |\n| **SSH Advanced** | Pooling, circuit breaker, retry strategies | Large-scale distributed operations |\n| **Backup System** | Multi-backend backups (Restic, Borg, Tar, Rsync) | Data protection & disaster recovery |\n| **GitOps Events** | Event-driven deployments from Git | Continuous deployment automation |\n| **Service Management** | Cross-platform services (systemd, launchd, runit) | Infrastructure service orchestration |\n\n---\n\n## Quick Start Commands\n\n### 🏃 30-Second Test\n\n```\n# 1. Check what runtimes you have available\nprovisioning runtime list\n\n# 2. Detect which runtime provisioning will use\nprovisioning runtime detect\n\n# 3. Verify runtime works\nprovisioning runtime info\n```\n\n**Expected Output**:\n\n```\nAvailable runtimes:\n  • docker\n  • podman\n```\n\n---\n\n## 1️⃣ Runtime Abstraction\n\n### What It Does\n\nAutomatically detects and uses Docker, Podman, OrbStack, Colima, or nerdctl - whichever is available on your system. Eliminates hardcoding "docker" commands.\n\n### Commands\n\n```\n# Detect available runtime\nprovisioning runtime detect\n# Output: "Detected runtime: docker"\n\n# Execute command in runtime\nprovisioning runtime exec "docker images"\n# Runs: docker images\n\n# Get runtime info\nprovisioning runtime info\n# Shows: name, command, version\n\n# List all available runtimes\nprovisioning runtime list\n# Shows: docker, podman, orbstack...\n\n# Adapt docker-compose for detected runtime\nprovisioning runtime compose ./docker-compose.yml\n# Output: docker compose -f ./docker-compose.yml\n```\n\n### Examples\n\n**Use Case 1: Works on macOS with OrbStack, Linux with Docker**\n\n```\n# User on macOS with OrbStack\n$ provisioning runtime exec "docker run -it ubuntu bash"\n# Automatically uses orbctl (OrbStack)\n\n# User on Linux with Docker\n$ provisioning runtime exec "docker run -it ubuntu bash"\n# Automatically uses docker\n```\n\n**Use Case 2: Run docker-compose with detected runtime**\n\n```\n# Detect and run compose\n$ compose_cmd=$(provisioning runtime compose ./docker-compose.yml)\n$ eval $compose_cmd up -d\n# Works with docker, podman, nerdctl automatically\n```\n\n### Configuration\n\nNo configuration needed! Runtime is auto-detected in order:\n\n1. Docker (macOS: OrbStack first; Linux: Docker first)\n2. Podman\n3. OrbStack (macOS)\n4. Colima (macOS)\n5. nerdctl\n\n---\n\n## 2️⃣ SSH Advanced Operations\n\n### What It Does\n\nAdvanced SSH with connection pooling (90% faster), circuit breaker for fault isolation, and deployment strategies (rolling, blue-green, canary).\n\n### Commands\n\n```\n# Create SSH pool connection to host\nprovisioning ssh pool connect server.example.com root --port 22 --timeout 30\n\n# Check pool status\nprovisioning ssh pool status\n\n# List available deployment strategies\nprovisioning ssh strategies\n# Output: rolling, blue-green, canary\n\n# Configure retry strategy\nprovisioning ssh retry-config exponential --max-retries 3\n\n# Check circuit breaker status\nprovisioning ssh circuit-breaker\n# Output: state=closed, failures=0/5\n```\n\n### Deployment Strategies\n\n| Strategy | Use Case | Risk |\n| ---------- | ---------- | ------ |\n| **Rolling** | Gradual rollout across hosts | Low (but slower) |\n| **Blue-Green** | Zero-downtime, instant rollback | Very low |\n| **Canary** | Test on small % before full rollout | Very low (5% at risk) |\n\n### Example: Multi-Host Deployment\n\n```\n# Set up SSH pool\nprovisioning ssh pool connect srv01.example.com root\nprovisioning ssh pool connect srv02.example.com root\nprovisioning ssh pool connect srv03.example.com root\n\n# Execute on pool (all 3 hosts in parallel)\nprovisioning ssh pool exec [srv01, srv02, srv03] "systemctl restart myapp" --strategy rolling\n\n# Check status\nprovisioning ssh pool status\n# Output: connections=3, active=0, idle=3, circuit_breaker=green\n```\n\n### Retry Strategies\n\n```\n# Exponential backoff: 100 ms, 200 ms, 400 ms, 800 ms...\nprovisioning ssh retry-config exponential --max-retries 5\n\n# Linear backoff: 100 ms, 200 ms, 300 ms, 400 ms...\nprovisioning ssh retry-config linear --max-retries 3\n\n# Fibonacci backoff: 100 ms, 100 ms, 200 ms, 300 ms, 500 ms...\nprovisioning ssh retry-config fibonacci --max-retries 4\n```\n\n---\n\n## 3️⃣ Backup System\n\n### What It Does\n\nMulti-backend backup management with Restic, BorgBackup, Tar, or Rsync. Supports local, S3, SFTP, REST API, and Backblaze B2 repositories.\n\n### Commands\n\n```\n# Create backup job\nprovisioning backup create daily-backup /data /var/lib \\n  --backend restic \\n  --repository s3://my-bucket/backups\n\n# Restore from snapshot\nprovisioning backup restore snapshot-001 --restore_path /data\n\n# List available snapshots\nprovisioning backup list\n\n# Schedule regular backups\nprovisioning backup schedule daily-backup "0 2 * * *" \\n  --paths ["/data" "/var/lib"] \\n  --backend restic\n\n# Show retention policy\nprovisioning backup retention\n# Output: daily=7, weekly=4, monthly=12, yearly=5\n\n# Check backup job status\nprovisioning backup status backup-job-001\n```\n\n### Backend Comparison\n\n| Backend | Speed | Compression | Best For |\n| --------- | ------- | ------------- | ---------- |\n| Restic | ⚡⚡⚡ | Excellent | Cloud backups |\n| BorgBackup | ⚡⚡ | Excellent | Large archives |\n| Tar | ⚡⚡⚡ | Good | Simple backups |\n| Rsync | ⚡⚡⚡ | None | Incremental syncs |\n\n### Example: Automated Daily Backups to S3\n\n```\n# Create backup configuration\nprovisioning backup create app-backup /opt/myapp /var/lib/myapp \\n  --backend restic \\n  --repository s3://prod-backups/myapp\n\n# Schedule daily at 2 AM\nprovisioning backup schedule app-backup "0 2 * * *"\n\n# Set retention: keep 7 days, 4 weeks, 12 months, 5 years\nprovisioning backup retention \\n  --daily 7 \\n  --weekly 4 \\n  --monthly 12 \\n  --yearly 5\n\n# Verify backup was created\nprovisioning backup list\n```\n\n### Dry-Run (Test First)\n\n```\n# Test backup without actually creating it\nprovisioning backup create test-backup /data --check\n\n# Test restore without actually restoring\nprovisioning backup restore snapshot-001 --check\n```\n\n---\n\n## 4️⃣ GitOps Event-Driven Deployments\n\n### What It Does\n\nAutomatically trigger deployments from Git events (push, PR, webhook, scheduled). Supports GitHub, GitLab, Gitea.\n\n### Commands\n\n```\n# Load GitOps rules from configuration file\nprovisioning gitops rules ./gitops-rules.yaml\n\n# Watch for Git events (starts webhook listener)\nprovisioning gitops watch --provider github --webhook-port 8080\n\n# List supported events\nprovisioning gitops events\n# Output: push, pull-request, webhook, scheduled, health-check, manual\n\n# Manually trigger deployment\nprovisioning gitops trigger deploy-prod --environment prod\n\n# List active deployments\nprovisioning gitops deployments --status running\n\n# Show GitOps status\nprovisioning gitops status\n# Output: active_rules=5, total=42, successful=40, failed=2\n```\n\n### Example: GitOps Configuration\n\n**File: `gitops-rules.yaml`**\n\n```\nrules:\n  - name: deploy-prod\n    provider: github\n    repository: https://github.com/myorg/myrepo\n    branch: main\n    events:\n      - push\n    targets:\n      - prod\n    command: "provisioning deploy"\n    require_approval: true\n\n  - name: deploy-staging\n    provider: github\n    repository: https://github.com/myorg/myrepo\n    branch: develop\n    events:\n      - push\n      - pull-request\n    targets:\n      - staging\n    command: "provisioning deploy"\n    require_approval: false\n```\n\n**Then:**\n\n```\n# Load rules\nprovisioning gitops rules ./gitops-rules.yaml\n\n# Watch for events\nprovisioning gitops watch --provider github\n\n# When you push to main, deployment auto-triggers!\n# git push origin main → provisioning deploy runs automatically\n```\n\n---\n\n## 5️⃣ Service Management\n\n### What It Does\n\nInstall, start, stop, and manage services across systemd (Linux), launchd (macOS), runit, and OpenRC.\n\n### Commands\n\n```\n# Install service\nprovisioning service install myapp /usr/local/bin/myapp \\n  --user myapp \\n  --working-dir /opt/myapp\n\n# Start service\nprovisioning service start myapp\n\n# Stop service\nprovisioning service stop myapp\n\n# Restart service\nprovisioning service restart myapp\n\n# Check service status\nprovisioning service status myapp\n# Output: running=true, uptime=86400s, restarts=2\n\n# List all services\nprovisioning service list\n\n# Detect init system\nprovisioning service detect-init\n# Output: systemd (Linux), launchd (macOS), etc.\n```\n\n### Example: Install Custom Service\n\n```\n# On Linux (systemd)\nprovisioning service install provisioning-worker \\n  /usr/local/bin/provisioning-worker \\n  --user provisioning \\n  --working-dir /opt/provisioning\n\n# On macOS (launchd) - works the same!\nprovisioning service install provisioning-worker \\n  /usr/local/bin/provisioning-worker \\n  --user provisioning \\n  --working-dir /opt/provisioning\n\n# Service file is generated automatically for your platform\nprovisioning service start provisioning-worker\nprovisioning service status provisioning-worker\n```\n\n---\n\n## 🎯 Common Workflows\n\n### Workflow 1: Multi-Platform Deployment\n\n```\n# Works on macOS with OrbStack, Linux with Docker, etc.\nprovisioning runtime detect          # Detects your platform\nprovisioning runtime exec "docker ps" # Uses your runtime\n```\n\n### Workflow 2: Large-Scale SSH Operations\n\n```\n# Connect to multiple servers\nfor host in srv01 srv02 srv03; do\n  provisioning ssh pool connect $host.example.com root\ndone\n\n# Execute in parallel with 3x retry\nprovisioning ssh pool exec [srv01, srv02, srv03] \\n  "systemctl restart app" \\n  --strategy rolling \\n  --retry exponential\n```\n\n### Workflow 3: Automated Backups\n\n```\n# Create backup job\nprovisioning backup create daily /opt/app /data \\n  --backend restic \\n  --repository s3://backups\n\n# Schedule for 2 AM every day\nprovisioning backup schedule daily "0 2 * * *"\n\n# Verify it works\nprovisioning backup list\n```\n\n### Workflow 4: Continuous Deployment from Git\n\n```\n# Define rules in YAML\ncat > gitops-rules.yaml << 'EOF'\nrules:\n  - name: deploy-prod\n    provider: github\n    repository: https://github.com/myorg/repo\n    branch: main\n    events: [push]\n    targets: [prod]\n    command: "provisioning deploy"\nEOF\n\n# Load and activate\nprovisioning gitops rules ./gitops-rules.yaml\nprovisioning gitops watch --provider github\n\n# Now pushing to main auto-deploys!\n```\n\n---\n\n## 🔧 Advanced Configuration\n\n### Using with Nickel Configuration\n\nAll integrations support Nickel schemas for advanced configuration:\n\n```\nlet { IntegrationConfig } = import "provisioning/integrations.ncl" in\n{\n  integrations = {\n    # Runtime configuration\n    runtime = {\n      preferred = "podman",\n      check_order = ["podman", "docker", "nerdctl"],\n      timeout_secs = 5,\n      enable_cache = true,\n    },\n\n    # Backup with retention policy\n    backup = {\n      default_backend = "restic",\n      default_repository = {\n        type = "s3",\n        bucket = "prod-backups",\n        prefix = "daily",\n      },\n      jobs = [],\n      verify_after_backup = true,\n    },\n\n    # GitOps rules with approval\n    gitops = {\n      rules = [],\n      default_strategy = "blue-green",\n      dry_run_by_default = false,\n      enable_audit_log = true,\n    },\n  }\n}\n```\n\n---\n\n## 💡 Tips & Tricks\n\n### Tip 1: Dry-Run Mode\n\nAll major operations support `--check` for testing:\n\n```\nprovisioning runtime exec "systemctl restart app" --check\n# Output: Would execute: [docker exec ...]\n\nprovisioning backup create test /data --check\n# Output: Backup would be created: [test]\n\nprovisioning gitops trigger deploy-test --check\n# Output: Deployment would trigger\n```\n\n### Tip 2: Output Formats\n\nSome commands support JSON output:\n\n```\nprovisioning runtime list --out json\nprovisioning backup list --out json\nprovisioning gitops deployments --out json\n```\n\n### Tip 3: Integration with Scripts\n\nChain commands in shell scripts:\n\n```\n#!/bin/bash\n\n# Detect runtime and use it\nRUNTIME=$(provisioning runtime detect | grep -oP 'docker|podman|nerdctl')\n\n# Execute using detected runtime\nprovisioning runtime exec "docker ps"\n\n# Create backup before deploy\nprovisioning backup create pre-deploy-$(date +%s) /opt/app\n\n# Deploy\nprovisioning deploy\n\n# Verify with GitOps\nprovisioning gitops status\n```\n\n---\n\n## 🐛 Troubleshooting\n\n### Problem: "No container runtime detected"\n\n**Solution**: Install Docker, Podman, or OrbStack:\n\n```\n# macOS\nbrew install orbstack\n\n# Linux\nsudo apt-get install docker.io\n\n# Then verify\nprovisioning runtime detect\n```\n\n### Problem: SSH connection timeout\n\n**Solution**: Check port and timeout settings:\n\n```\n# Use different port\nprovisioning ssh pool connect server.example.com root --port 2222\n\n# Increase timeout\nprovisioning ssh pool connect server.example.com root --timeout 60\n```\n\n### Problem: Backup fails with "Permission denied"\n\n**Solution**: Check permissions on backup path:\n\n```\n# Check if user can read target paths\nls -l /data  # Should be readable\n\n# Run with elevated privileges if needed\nsudo provisioning backup create mybak /data --backend restic\n```\n\n---\n\n## 📚 Learn More\n\n| Topic | Location |\n| ------- | ---------- |\n| Architecture | `docs/architecture/ECOSYSTEM_INTEGRATION.md` |\n| CLI Help | `provisioning help integrations` |\n| Rust Bridge | `provisioning/platform/integrations/provisioning-bridge/` |\n| Nushell Modules | `provisioning/core/nulib/lib_provisioning/integrations/` |\n| Nickel Schemas | `provisioning/schemas/integrations/` |\n\n---\n\n## 🆘 Need Help\n\n```\n# General help\nprovisioning help integrations\n\n# Specific command help\nprovisioning runtime --help\nprovisioning backup --help\nprovisioning gitops --help\n\n# System diagnostics\nprovisioning status\nprovisioning health\n```\n\n---\n\n**Last Updated**: 2025-11-23\n**Version**: 1.0.0
