vm-tool 1.0.32__py3-none-any.whl

examples/README.md

@@ -0,0 +1,5 @@
+## SSH Key Management
+- `ssh_key_management.py`: Generate/manage SSH keys and configure VM for SSH access
+
+## Version Check
+- `version_check.sh`: Check installed version of vm_tool

examples/__init__.py

@@ -0,0 +1 @@
+# Example scripts package

examples/cloud/README.md

@@ -0,0 +1,3 @@
+# Cloud Examples
+
+Use `template_cloud_setup.py` as your starting point for any cloud VM setup scenario. Other files are legacy or specific examples and can be removed if you only want the template.

examples/cloud/__init__.py

@@ -0,0 +1 @@
+# Cloud VM setup examples package

examples/cloud/ssh_identity_file.py

@@ -0,0 +1,27 @@
+"""
+Example: Cloud VM setup using SSH key authentication (public GitHub repo).
+- Connects to a remote VM using SSH key and runs setup from a public repo.
+"""
+
+from vm_tool.runner import SetupRunner, SetupRunnerConfig, SSHConfig
+
+
+def main():
+    config = SetupRunnerConfig(
+        github_project_url="https://github.com/username/public-repo",
+        github_branch="main",
+        docker_compose_file_path="docker-compose.yml",
+    )
+    runner = SetupRunner(config)
+    ssh_configs = [
+        SSHConfig(
+            ssh_username="your_ssh_username",
+            ssh_hostname="your_ssh_hostname",
+            ssh_identity_file="/path/to/your/ssh_key",
+        )
+    ]
+    runner.run_cloud_setup(ssh_configs)
+
+
+if __name__ == "__main__":
+    main()

examples/cloud/ssh_password.py

@@ -0,0 +1,27 @@
+"""
+Example: Cloud VM setup using SSH password authentication (public GitHub repo).
+- Connects to a remote VM using SSH username/password and runs setup from a public repo.
+"""
+
+from vm_tool.runner import SetupRunner, SetupRunnerConfig, SSHConfig
+
+
+def main():
+    config = SetupRunnerConfig(
+        github_project_url="https://github.com/username/public-repo",
+        github_branch="main",
+        docker_compose_file_path="docker-compose.yml",
+    )
+    runner = SetupRunner(config)
+    ssh_configs = [
+        SSHConfig(
+            ssh_username="your_ssh_username",
+            ssh_hostname="your_ssh_hostname",
+            ssh_password="your_ssh_password",
+        )
+    ]
+    runner.run_cloud_setup(ssh_configs)
+
+
+if __name__ == "__main__":
+    main()

examples/cloud/template_cloud_setup.py

@@ -0,0 +1,36 @@
+"""
+Template: Cloud VM setup (customize for your use case)
+- Use this template to create your own cloud VM setup script.
+- Supports public/private GitHub, DockerHub, SSH key or password authentication, and multiple VMs.
+- Fill in only the fields you need for your scenario.
+"""
+
+from vm_tool.runner import SetupRunner, SetupRunnerConfig, SSHConfig
+
+
+def main():
+    # Fill in only the fields you need for your use case
+    config = SetupRunnerConfig(
+        github_username=None,  # e.g., 'your_github_username' (for private repos)
+        github_token=None,  # e.g., 'your_github_token' (for private repos)
+        github_project_url="https://github.com/username/your-repo",
+        github_branch="main",  # Optional, defaults to 'main'
+        docker_compose_file_path="docker-compose.yml",  # Optional
+        dockerhub_username=None,  # e.g., 'your_dockerhub_username' (if DockerHub login needed)
+        dockerhub_password=None,  # e.g., 'your_dockerhub_password' (if DockerHub login needed)
+    )
+    runner = SetupRunner(config)
+    ssh_configs = [
+        SSHConfig(
+            ssh_username="your_ssh_username",
+            ssh_hostname="your_ssh_hostname",
+            ssh_identity_file=None,  # e.g., '/path/to/your/ssh_key' (for SSH key auth)
+            ssh_password=None,  # e.g., 'your_ssh_password' (for SSH password auth)
+        )
+        # Add more SSHConfig instances for multiple VMs if needed
+    ]
+    runner.run_cloud_setup(ssh_configs)
+
+
+if __name__ == "__main__":
+    main()

examples/deploy_full_setup.py

@@ -0,0 +1,44 @@
+"""
+Example deployment script using run_cloud_setup for full VM provisioning.
+This approach installs Docker, clones your repo, and sets up everything.
+"""
+
+import os
+from vm_tool.runner import SetupRunner, SetupRunnerConfig, SSHConfig
+
+# Configuration
+config = SetupRunnerConfig(
+    github_username=os.environ.get("GITHUB_USERNAME"),
+    github_token=os.environ.get("GITHUB_TOKEN"),
+    github_project_url=os.environ.get(
+        "GITHUB_PROJECT_URL", "https://github.com/user/repo.git"
+    ),
+    github_branch=os.environ.get("GITHUB_BRANCH", "main"),
+    docker_compose_file_path=os.environ.get(
+        "DOCKER_COMPOSE_FILE", "docker-compose.yml"
+    ),
+    dockerhub_username=os.environ.get("DOCKERHUB_USERNAME"),
+    dockerhub_password=os.environ.get("DOCKERHUB_PASSWORD"),
+)
+
+# Initialize runner
+runner = SetupRunner(config)
+
+# SSH configuration for target VM(s)
+ssh_configs = [
+    SSHConfig(
+        ssh_username=os.environ.get("EC2_USER", "ubuntu"),
+        ssh_hostname=os.environ.get("EC2_HOST"),
+        ssh_identity_file=os.environ.get("SSH_IDENTITY_FILE", "~/.ssh/id_rsa"),
+    ),
+]
+
+# Run full cloud setup
+print("🚀 Starting full VM setup...")
+print(f"   Target: {ssh_configs[0].ssh_hostname}")
+print(f"   Repository: {config.github_project_url}")
+print(f"   Branch: {config.github_branch}")
+
+runner.run_cloud_setup(ssh_configs)
+
+print("✅ VM setup complete!")

examples/docker-compose.example.yml

@@ -0,0 +1,47 @@
+version: "3.8"
+
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+    volumes:
+      - ./html:/usr/share/nginx/html
+    restart: unless-stopped
+    healthcheck:
+      test:
+        ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  api:
+    image: python:3.11-slim
+    working_dir: /app
+    volumes:
+      - ./app:/app
+    command: python -m http.server 8000
+    ports:
+      - "8000:8000"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    environment:
+      - ENVIRONMENT=production
+      - LOG_LEVEL=info
+
+  redis:
+    image: redis:alpine
+    ports:
+      - "6379:6379"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 30s
+      timeout: 3s
+      retries: 3

examples/ec2-setup.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+
+# EC2 Setup Script for GitHub Actions Deployment
+# Run this on your EC2 instance
+
+set -e
+
+echo "🚀 Setting up EC2 for GitHub Actions Deployment"
+echo "================================================"
+
+# Update system
+echo "📦 Updating system packages..."
+sudo apt update && sudo apt upgrade -y
+
+# Install Docker
+echo "🐳 Installing Docker..."
+if ! command -v docker &> /dev/null; then
+    curl -fsSL https://get.docker.com -o get-docker.sh
+    sudo sh get-docker.sh
+    rm get-docker.sh
+    echo "✅ Docker installed"
+else
+    echo "✅ Docker already installed"
+fi
+
+# Install Docker Compose
+echo "🐳 Installing Docker Compose..."
+if ! command -v docker-compose &> /dev/null; then
+    sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+    sudo chmod +x /usr/local/bin/docker-compose
+    echo "✅ Docker Compose installed"
+else
+    echo "✅ Docker Compose already installed"
+fi
+
+# Create deploy user
+echo "👤 Creating deploy user..."
+if ! id "deploy" &>/dev/null; then
+    sudo adduser --disabled-password --gecos "" deploy
+    sudo usermod -aG docker deploy
+    sudo usermod -aG sudo deploy
+    echo "✅ Deploy user created"
+else
+    echo "✅ Deploy user already exists"
+fi
+
+# Add current user to docker group
+echo "👤 Adding $USER to docker group..."
+sudo usermod -aG docker $USER
+
+# Create app directory
+echo "📁 Creating app directory..."
+sudo mkdir -p /home/deploy/app
+sudo chown -R deploy:deploy /home/deploy/app
+
+# Create backups directory
+echo "📁 Creating backups directory..."
+sudo mkdir -p /home/deploy/backups
+sudo chown -R deploy:deploy /home/deploy/backups
+
+# Install useful tools
+echo "🛠️  Installing useful tools..."
+sudo apt install -y git curl wget htop ncdu
+
+# Configure firewall
+echo "🔒 Configuring firewall..."
+if command -v ufw &> /dev/null; then
+    sudo ufw allow 22/tcp    # SSH
+    sudo ufw allow 80/tcp    # HTTP
+    sudo ufw allow 443/tcp   # HTTPS
+    sudo ufw allow 8000/tcp  # App port (adjust as needed)
+    echo "✅ Firewall configured (not enabled yet)"
+    echo "⚠️  To enable: sudo ufw enable"
+else
+    echo "⚠️  UFW not installed"
+fi
+
+# Print SSH public key location
+echo ""
+echo "================================================"
+echo "✅ EC2 Setup Complete!"
+echo "================================================"
+echo ""
+echo "Next steps:"
+echo "1. Add your GitHub Actions public key to ~/.ssh/authorized_keys"
+echo "2. Test SSH connection from your local machine"
+echo "3. Configure your GitHub repository secrets"
+echo ""
+echo "To add SSH key:"
+echo "  mkdir -p ~/.ssh"
+echo "  echo 'YOUR_PUBLIC_KEY' >> ~/.ssh/authorized_keys"
+echo "  chmod 600 ~/.ssh/authorized_keys"
+echo "  chmod 700 ~/.ssh"
+echo ""
+echo "Logout and login again to apply docker group changes"

examples/github-actions-ec2.yml

@@ -0,0 +1,245 @@
+name: Deploy to EC2 with vm_tool
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+env:
+  EC2_HOST: ${{ secrets.EC2_HOST }}
+  EC2_USER: ${{ secrets.EC2_USER }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Validate Required Secrets
+        run: |
+          echo "🔐 Validating GitHub Secrets..."
+          MISSING_SECRETS=()
+          
+          # Check EC2_HOST
+          if [ -z "${{ secrets.EC2_HOST }}" ]; then
+            MISSING_SECRETS+=("EC2_HOST")
+          fi
+          
+          # Check EC2_USER
+          if [ -z "${{ secrets.EC2_USER }}" ]; then
+            MISSING_SECRETS+=("EC2_USER")
+          fi
+          
+          # Check EC2_SSH_KEY
+          if [ -z "${{ secrets.EC2_SSH_KEY }}" ]; then
+            MISSING_SECRETS+=("EC2_SSH_KEY")
+          fi
+          
+          # If any secrets are missing, show detailed instructions
+          if [ ${#MISSING_SECRETS[@]} -ne 0 ]; then
+            echo ""
+            echo "❌ ERROR: Missing required GitHub Secrets!"
+            echo ""
+            echo "Missing secrets: ${MISSING_SECRETS[*]}"
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "📝 How to add GitHub Secrets:"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            echo "1. Go to your GitHub repository"
+            echo "2. Click: Settings → Secrets and variables → Actions"
+            echo "3. Click: New repository secret"
+            echo "4. Add each secret:"
+            echo ""
+            
+            if [[ " ${MISSING_SECRETS[*]} " =~ " EC2_HOST " ]]; then
+              echo "   📍 EC2_HOST"
+              echo "      Value: Your EC2 instance IP address"
+              echo "      Example: 54.123.45.67"
+              echo ""
+            fi
+            
+            if [[ " ${MISSING_SECRETS[*]} " =~ " EC2_USER " ]]; then
+              echo "   👤 EC2_USER"
+              echo "      Value: SSH username for your EC2 instance"
+              echo "      Example: ubuntu (for Ubuntu) or ec2-user (for Amazon Linux)"
+              echo ""
+            fi
+            
+            if [[ " ${MISSING_SECRETS[*]} " =~ " EC2_SSH_KEY " ]]; then
+              echo "   🔑 EC2_SSH_KEY"
+              echo "      Value: Your SSH private key"
+              echo ""
+              echo "      To get your SSH private key, run on your LOCAL machine:"
+              echo "      $ cat ~/.ssh/id_rsa"
+              echo ""
+              echo "      OR if you use ed25519:"
+              echo "      $ cat ~/.ssh/id_ed25519"
+              echo ""
+              echo "      Copy the ENTIRE output (including BEGIN and END lines)"
+              echo ""
+              echo "      Don't have an SSH key? Generate one:"
+              echo "      $ ssh-keygen -t ed25519 -C 'github-actions'"
+              echo "      $ cat ~/.ssh/id_ed25519.pub  # Add to EC2 ~/.ssh/authorized_keys"
+              echo "      $ cat ~/.ssh/id_ed25519      # Add to GitHub Secrets"
+              echo ""
+            fi
+            
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "📚 For detailed instructions, see:"
+            echo "   - docs/ec2-github-actions-guide.md"
+            echo "   - docs/ssh-key-setup.md"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            exit 1
+          fi
+          
+          echo "✅ All required secrets are configured"
+          echo "   - EC2_HOST: ${{ secrets.EC2_HOST }}"
+          echo "   - EC2_USER: ${{ secrets.EC2_USER }}"
+          echo "   - EC2_SSH_KEY: ✓ (configured)"
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install vm_tool
+        run: pip install vm-tool
+
+      - name: Set up SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.EC2_SSH_KEY }}" > ~/.ssh/deploy_key
+          chmod 600 ~/.ssh/deploy_key
+          ssh-keyscan -H ${{ secrets.EC2_HOST }} >> ~/.ssh/known_hosts
+
+      - name: Validate SSH Connection
+        run: |
+          if [ ! -s ~/.ssh/deploy_key ]; then
+            echo "❌ ERROR: EC2_SSH_KEY is empty!"
+            echo ""
+            echo "📝 To get your SSH key, run on your local machine:"
+            echo "   cat ~/.ssh/id_rsa"
+            echo ""
+            echo "Then add it to GitHub Secrets as EC2_SSH_KEY"
+            echo "See: docs/ssh-key-setup.md for detailed instructions"
+            exit 1
+          fi
+          
+          echo "✅ Testing SSH connection..."
+          ssh -i ~/.ssh/deploy_key -o StrictHostKeyChecking=no \
+            ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} "echo 'Connection successful'" || {
+            echo "❌ SSH connection failed!"
+            echo "Check: docs/ssh-key-setup.md for troubleshooting"
+            exit 1
+          }
+
+      - name: Copy project files to EC2
+        run: |
+          # Create app directory if it doesn't exist
+          ssh -i ~/.ssh/deploy_key ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} \
+            'mkdir -p ~/app'
+          
+          # Copy docker-compose and related files
+          scp -i ~/.ssh/deploy_key docker-compose.yml \
+            ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}:~/app/
+          
+          # Copy application code
+          rsync -avz -e "ssh -i ~/.ssh/deploy_key" \
+            --exclude '.git' \
+            --exclude 'node_modules' \
+            --exclude '.env' \
+            ./ ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}:~/app/
+
+      - name: Create backup before deployment
+        run: |
+          ssh -i ~/.ssh/deploy_key ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} << 'EOF'
+            mkdir -p ~/backups
+            BACKUP_FILE=~/backups/backup-$(date +%Y%m%d-%H%M%S).tar.gz
+            if [ -d ~/app ]; then
+              cd ~/app && tar -czf $BACKUP_FILE . || true
+              echo "Backup created: $BACKUP_FILE"
+            fi
+          EOF
+
+      - name: Deploy with Docker Compose
+        run: |
+          ssh -i ~/.ssh/deploy_key ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} << 'EOF'
+            cd ~/app
+            
+            # Pull latest images
+            docker-compose pull
+            
+            # Stop old containers
+            docker-compose down
+            
+            # Start new containers
+            docker-compose up -d --build
+            
+            # Wait for services to start
+            sleep 10
+          EOF
+
+      - name: Health check
+        run: |
+          # Wait for application to be ready
+          for i in {1..30}; do
+            if curl -f http://${{ secrets.EC2_HOST }}:8000/health 2>/dev/null; then
+              echo "✅ Health check passed"
+              exit 0
+            fi
+            echo "Waiting for application... ($i/30)"
+            sleep 2
+          done
+          echo "❌ Health check failed"
+          exit 1
+
+      - name: Verify deployment
+        run: |
+          ssh -i ~/.ssh/deploy_key ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} << 'EOF'
+            cd ~/app
+            echo "📊 Container status:"
+            docker-compose ps
+            echo ""
+            echo "📝 Recent logs:"
+            docker-compose logs --tail=50
+          EOF
+
+      - name: Rollback on failure
+        if: failure()
+        run: |
+          echo "⚠️  Deployment failed, attempting rollback..."
+          ssh -i ~/.ssh/deploy_key ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} << 'EOF'
+            cd ~/app
+            LATEST_BACKUP=$(ls -t ~/backups/*.tar.gz 2>/dev/null | head -1)
+            if [ -n "$LATEST_BACKUP" ]; then
+              echo "Rolling back to: $LATEST_BACKUP"
+              tar -xzf $LATEST_BACKUP
+              docker-compose up -d
+              echo "✅ Rollback complete"
+            else
+              echo "❌ No backup found for rollback"
+            fi
+          EOF
+
+      - name: Cleanup old backups
+        if: success()
+        run: |
+          ssh -i ~/.ssh/deploy_key ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} << 'EOF'
+            # Keep only last 5 backups
+            cd ~/backups
+            ls -t *.tar.gz 2>/dev/null | tail -n +6 | xargs rm -f || true
+            echo "✅ Cleanup complete"
+          EOF
+
+      - name: Send notification
+        if: always()
+        run: |
+          if [ "${{ job.status }}" == "success" ]; then
+            echo "✅ Deployment successful to ${{ secrets.EC2_HOST }}"
+          else
+            echo "❌ Deployment failed to ${{ secrets.EC2_HOST }}"
+          fi

examples/github-actions-full-setup.yml

@@ -0,0 +1,58 @@
+name: Full VM Setup and Deploy
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install vm_tool
+        run: |
+          python -m pip install --upgrade pip
+          pip install vm-tool
+
+      - name: Create SSH identity file
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.EC2_SSH_KEY }}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -H ${{ secrets.EC2_HOST }} >> ~/.ssh/known_hosts
+
+      - name: Full VM Setup and Deploy
+        env:
+          GITHUB_USERNAME: ${{ secrets.GITHUB_USERNAME }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_PROJECT_URL: ${{ github.server_url }}/${{ github.repository }}
+          GITHUB_BRANCH: ${{ github.ref_name }}
+          DOCKER_COMPOSE_FILE: docker-compose.prod.yml
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
+          EC2_USER: ${{ secrets.EC2_USER }}
+          EC2_HOST: ${{ secrets.EC2_HOST }}
+          SSH_IDENTITY_FILE: ~/.ssh/id_rsa
+        run: python scripts/deploy_to_vm.py
+
+      - name: Clean up SSH identity file
+        if: always()
+        run: rm -f ~/.ssh/id_rsa
+
+      - name: Notify
+        if: always()
+        run: |
+          if [ "${{ job.status }}" == "success" ]; then
+            echo "✅ Full setup and deployment successful!"
+          else
+            echo "❌ Deployment failed"
+          fi

examples/local/.keep

@@ -0,0 +1 @@
+# Keep this directory for local examples and templates.

examples/local/README.md

@@ -0,0 +1,3 @@
+# Local Examples
+
+Use `template_local_setup.py` as your starting point for any local VM setup scenario. Other files are legacy or specific examples and can be removed if you only want the template.

examples/local/__init__.py

@@ -0,0 +1 @@
+# Local VM setup examples package

examples/local/template_local_setup.py

@@ -0,0 +1,27 @@
+"""
+Template: Local VM setup (customize for your use case)
+- Use this template to create your own local VM setup script.
+- Supports public/private GitHub, DockerHub, and custom Docker Compose file path.
+- Fill in only the fields you need for your scenario.
+"""
+
+from vm_tool.runner import SetupRunner, SetupRunnerConfig
+
+
+def main():
+    # Fill in only the fields you need for your use case
+    config = SetupRunnerConfig(
+        github_username=None,  # e.g., 'your_github_username' (for private repos)
+        github_token=None,  # e.g., 'your_github_token' (for private repos)
+        github_project_url="https://github.com/username/your-repo",
+        github_branch="main",  # Optional, defaults to 'main'
+        docker_compose_file_path="docker-compose.yml",  # Optional
+        dockerhub_username=None,  # e.g., 'your_dockerhub_username' (if DockerHub login needed)
+        dockerhub_password=None,  # e.g., 'your_dockerhub_password' (if DockerHub login needed)
+    )
+    runner = SetupRunner(config)
+    runner.run_setup()
+
+
+if __name__ == "__main__":
+    main()