Docker VPS Deploy

Overview

Build Docker image in CI, compress with gzip, transfer to VPS via rsync over SSH, load and run with Docker Compose. No container registry required — the image travels as a .tar.gz file.

When to Use

• VPS with SSH access, Docker, and Docker Compose installed
• No container registry in the workflow (no Docker Hub, ECR, GHCR, etc.)
• Single-server or small-fleet deployment
• User asks to generate a GitHub Actions workflow for VPS deployment via rsync/SSH

When NOT to Use

• Container registry already available → push/pull is simpler and faster
• Cloud-managed deployments (ECS, Cloud Run, Fly.io, Railway, Render)
• Multi-node orchestration (Kubernetes, Docker Swarm across nodes)
• Non-Docker deployments (bare-metal, systemd services)

Prerequisites

On the VPS before first run:

• Docker and Docker Compose v2 (docker compose, not docker-compose) installed
• SSH key-based authentication configured for deploy user
• Deploy directory exists and is writable (e.g., /opt/app)
• docker-compose.yml present in the repository root

Required Secrets

Add in: GitHub repo → Settings → Secrets and variables → Actions.

Core Pipeline Pattern

name: Deploy to VPS

on:
  push:
    branches: [main]
    paths-ignore:
      - "*.md"
      - "docs/**"

env:
  IMAGE_NAME: my-app
  DEPLOY_DIR: /opt/app

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build Docker image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ./Dockerfile
          load: true
          tags: ${{ env.IMAGE_NAME }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Save and compress image
        run: docker save ${{ env.IMAGE_NAME }}:latest | gzip > image.tar.gz

      - name: Setup SSH agent
        uses: webfactory/[email protected]
        with:
          ssh-private-key: ${{ secrets.SSH_KEY }}

      - name: Add VPS to known hosts
        run: ssh-keyscan -p ${{ secrets.SSH_PORT }} -H ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts

      - name: Transfer files to VPS
        run: |
          rsync -avz \
            -e "ssh -p ${{ secrets.SSH_PORT }} -o StrictHostKeyChecking=yes" \
            image.tar.gz docker-compose.yml \
            ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:${{ env.DEPLOY_DIR }}/

      - name: Deploy on VPS
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          port: ${{ secrets.SSH_PORT }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd ${{ env.DEPLOY_DIR }}
            gunzip -c image.tar.gz | docker load
            docker compose down
            docker compose up -d
            docker image prune -f
            rm -f image.tar.gz

Key Optimizations

• Layer caching (`type=gha`, `mode=max`): GitHub Actions cache backend. Skips rebuild of unchanged layers. mode=max caches all intermediate layers, not just the final stage.
• Gzip compression: docker save outputs uncompressed tar. Gzip reduces image size 60–70% before transfer. For images >2 GB, consider zstd (docker save ... | zstd) for faster compression.
• `webfactory/ssh-agent`: Loads the deploy key into ssh-agent in memory — no key file written to disk. Integrates with the system SSH client, so rsync and other SSH commands work without -i flags.
• `appleboy/ssh-action`: Executes remote Docker commands over SSH with a clean YAML interface. Errors and stdout are surfaced natively in the Actions log without manual heredoc handling.
• rsync `-avz`: Archive mode + compression during transfer. Subsequent deploys only transfer changed bytes (docker-compose.yml updates are nearly instant).
• `load: true`: Required in build-push-action when NOT pushing to a registry. Makes the built image available locally for docker save.

Security Considerations

• Never use `StrictHostKeyChecking=no`. Use ssh-keyscan to populate known_hosts before connecting. Disabling host key checking enables MITM attacks.
• SSH key never written to disk. webfactory/ssh-agent loads the key into ssh-agent in memory. appleboy/ssh-action handles its own key internally — no files, no CLI args.
• Ed25519 keys preferred over RSA — smaller, faster, same security.
• Dedicated deploy user on the VPS: non-root, member of docker group, write access to deploy dir only.
• `permissions: contents: read` — least-privilege GITHUB_TOKEN scoping.

Common Mistakes

Cross-Reference

For GitHub Actions syntax fundamentals — workflow YAML structure, triggers, job orchestration, caching patterns, action SHA pinning, and the 13 common anti-patterns — use the github-actions skill:

npx skills add oakoss/agent-skills/github-actions

This skill focuses exclusively on the Docker + VPS rsync-based deployment pattern and delegates all GitHub Actions syntax questions to that skill.