Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    Docker Deploy to VPS with Auto-Rollback (GitHub Actions)

    1

    Generic prompting writes the happy path and none of the failure paths.

    $12

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Docker Deploy to VPS with Auto-Rollback (GitHub Actions)

    Docker Deploy to VPS with Auto-Rollback (GitHub Actions)

    Example session with this skill installed

    Set up GitHub Actions to build this app's Docker image, push it to GHCR, and deploy it to my DigitalOcean droplet over SSH. If the new container fails its healthcheck, roll back to the previous image. I can't give you SSH access right now — the droplet is Ubuntu 24.04, 1 GB RAM, Docker and Compose v2 are installed, and nginx already holds ports 80 and 443 for another site. The app is notes-api.example.com.

    • Read your context and instructions
    • Compiled the docker deploy to

    notes-api: GHCR build and SSH deploy to the droplet

    The pipeline is written and the deploy script passes all 10 rollback scenarios in the test harness. Nothing has run against your droplet or GitHub yet. One value needs your input before the first build: the GHCR owner in the compose file's image: line. The repo has no git remote, so I couldn't tell which GitHub account or org it lives under.

    Files created

    • .github/workflows/deploy.yml: the CI/CD workflow
    • Dockerfile, .dockerignore, .gitignore
    • deploy/docker-compose.yml: the service definition the droplet runs
    • deploy/deploy.sh: the script that runs on the droplet, including rollback
    • deploy/app.env.example: template for the secrets file
    • deploy/nginx/notes-api.conf: nginx site file for notes-api.example.com
    • deploy/SETUP.md: setup steps and runbook for the droplet
    • deploy/test-deploy-script.sh: an unmodified copy of the skill's test harness, so CI re-runs it on every PR

    Nothing is committed.

    Workflow, triggers and gates

    • Triggers: push to main, pull requests to main, and manual dispatch.
    • Build job, every run:
      1. Checks that the compose image: line equals ghcr.io/<owner>/<repo> in lowercase, and fails with the exact expected line if it doesn't.
      2. Runs bash -n and shellcheck on deploy.sh.
      3. Runs the harness.
      4. Builds the image for linux/amd64.
    • PRs build but never push or deploy. Superseded PR runs are cancelled.
    • Deploy job runs only if all of these hold:
      • the event is not a pull request
      • the branch is main
      • the repo variable DEPLOY_ENABLED is 'true'
      • the build job passed

    Deploy queue: deploys run one at a time and are never cancelled, because a cancelled deploy stops mid-script with no rollback.

    • Timeouts: 30 minutes for the build job, 15 for the deploy job.

    Which files CI owns and which live only on the droplet

    Path on dropletWritten by
    /opt/notes-api/docker-compose.ymlCI on every deploy. It is staged in incoming/, the old copy is backed up, then the new one is installed and checked with docker compose config -q
    /opt/notes-api/.envCI on every deploy. It holds TAG= and nothing else
    /opt/notes-api/app.envOnly you, by hand: chmod 600, never in git, CI never touches it
    /etc/nginx/sites-available/notes-apiOnly you, by hand. The copy in git is for reference
    deploy.shNever stored on the droplet; it is sent over SSH from the checkout

    CI uploads exactly one named file and never syncs the directory, so app.env can't be deleted by a deploy.

    Image tags and rollback reach

    • Every deploy uses an immutable sha-<7> tag from docker/metadata-action. The tag is computed once in the build job and passed to the deploy job.

    Automatic rollback runs when the pull fails, the container fails to start, or it isn't healthy within 120s. The image's worst case to unhealthy is about 45s. Rollback restores both the previous compose file and the previous tag. It then re-checks health and prints either rolled back to … — healthy or ROLLBACK FAILED — … intervene now.

    How far back: each successful deploy prunes this app's images older than 7 days. The prune only touches images carrying this repo's source label, so the other site's images are safe. To go back further, pull the old tag by hand with a long-lived token (steps in SETUP.md).

    First deploy: if it fails, there is no previous tag. The script says so and exits 1 without pretending it recovered.

    Secrets

    • Environment production: SSH_HOST, SSH_USER (deploy), SSH_PRIVATE_KEY.
      • If one is missing, or the environment: line is removed, the value comes through as an empty string. The SSH step then fails, unless an old repo-level SSH_* secret with the same name exists, in which case it would quietly deploy to that host. Run gh secret list first and delete any leftovers.
    • No passphrase secret is referenced, so the CI key must be generated with -N "".

    Registry access: the job's own GITHUB_TOKEN is passed to the droplet through the action's envs: input, used for docker login, and logged out on exit. No registry credential stays on the droplet.

    • Repo variable DEPLOY_ENABLED: start it at false.

    Runtime secrets: DATABASE_URL goes in /opt/notes-api/app.env, never in build args or ENV. If that file is missing, the deploy stops before changing anything and the error names app.env.

    Ports

    • The container is published on 127.0.0.1:8000:8000 only, and nginx proxies notes-api.example.com to it.
    • No container port is published on a public interface. Ports 80 and 443 stay with your existing nginx; I only added one site file.
    • Other limits for the shared 1 GB box:
      • mem_limit: 256m
      • logs capped at 10m × 3 files
      • init: true, because main.py doesn't handle SIGTERM and would otherwise wait the full 10s on every stop

    Test results

    The harness ran against deploy/deploy.sh with a fake docker (no daemon, no server). Real output:

    deploy script: deploy/deploy.sh
    
      ok   1  happy path                              rc=0  tag=TAG=sha-NEW config=NEW-CONFIG
      ok   2  shipped config invalid                  rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   3  up -d fails                             rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   4  container unhealthy                     rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   5  rollback unhealthy                      rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   6  rollback up -d fails                    rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   7  no previous tag                         rc=1  tag=TAG=sha-NEW config=OLD-CONFIG
      ok   8  registry pull fails                     rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   9  registry login fails                    rc=1  tag=TAG=sha-OLD config=OLD-CONFIG
      ok   10 host prerequisite missing               rc=1  error names app.env, nothing mutated
    
    passed=10 failed=0
    

    It passed on the first run. To check that the harness actually catches bugs, I made a throwaway copy of the script with the registry-pull failure no longer caught. Case 8 then failed: FAIL 8 registry pull fails config='NEW-CONFIG'(want 'OLD-CONFIG') missing-output='rolled back' stale-.prev-left-behind. I deleted that copy afterwards.

    Other checks

    • bash -n and sh -n on deploy.sh both pass.
    • docker compose config -q on the real compose file passes with local Compose

    v2.39.1, and fails as expected when app.env is missing. This runs client-side and needs no daemon.

    • The healthcheck probe exits 0 against the app running locally and 1 once it's stopped. That was local Python 3.14.0, not inside the image.
    • The workflow YAML parses. The compose-image check passes on a matching repo name and fails on a mismatched one.

    Not tested or verified:

    • The control-flow tests prove which branch the script takes, not how real Docker behaves.
    • No image was built and no Docker daemon was used.
    • shellcheck and actionlint aren't installed here. The CI step assumes ubuntu-latest ships shellcheck.
    • The action versions (checkout@v4, login-action@v3, metadata-action@v5, build-push-action@v6, scp-action@v1.0.0, ssh-action@v1.2.0) and python:3.14-slim were not checked against the latest releases, since I had no network access.
    • Nothing was checked on the droplet, so all of these are unconfirmed:
      • whether port 8000 is free
      • your exact Compose v2 version (the top-level name: needs a recent v2)
      • your nginx version, which decides which HTTP/2 listen line stage 2 uses
      • swap, ufw state, any existing daemon.json
      • x86_64 architecture
      • that the SSH user's shell is bash
    • /healthz doesn't touch the database, so a wrong DATABASE_URL still deploys as healthy.
    • The SSH step doesn't pin the host key. appleboy/ssh-action supports a fingerprint: input if you want that.

    By hand before the first deploy (details in deploy/SETUP.md)

    1. Set image: in deploy/docker-compose.yml to ghcr.io/<owner>/<repo> in lowercase. The build fails until you do.
    2. On the droplet, run the read-only checks listed in SETUP.md: port 8000, docker compose version, nginx -v, swap, uname -m.
    3. Take a backup. Add a 1 GB swapfile if there's none.
    4. Merge the Docker log-rotation settings into daemon.json rather than overwriting it.
    5. Create the deploy user in the docker group and /opt/notes-api owned by it.
    6. Type app.env on the droplet (chmod 600).
    7. Generate the CI key on your machine and add its public key to ~deploy/.ssh/authorized_keys.
    8. In GitHub, create the production environment, add its 3 secrets, and set DEPLOY_ENABLED=false.
    9. Point an A record at the droplet, then install nginx stage 1, then run certbot certonly --webroot, then switch to stage 2. Use nginx -t before every reload, and confirm the other site still answers each time.
    10. Merge, watch the build pass, flip DEPLOY_ENABLED to true, and deploy. Then check that ss -tlnp shows 127.0.0.1:8000, and that nc -z <droplet-ip> 8000 from outside the droplet fails.
    11. Deploy twice, then push a commit that breaks /healthz and confirm the real rollback recovers the service, all before it carries traffic.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    The problem

    Self-hosted deploys rarely fail loudly. The usual failure is a deploy that reports success while the app is down, a rollback that set -e silently skipped, a published port that Docker exposes past ufw, or an rsync --delete that wipes the host's secrets file. Generic prompting writes the happy path and none of the failure paths.

    What it does

    • Sets up the full pipeline: build on the runner, push to a registry, deploy over SSH, roll back.
    • Writes the remote deploy script with preflight checks, a paired restore for every mutation, and a rollback that re-checks health before it claims success.
    • Draws the ownership boundary first: which files CI ships every deploy, which live only on the host, and why mixing them causes silent breakage.
    • Deploys immutable sha-<short> tags, never latest, so rollback is a tag swap.
    • Scopes secrets with GitHub Environments and keeps them out of build args, ENV and compose files.
    • Prepares a fresh VM in a safe order and binds ports to 127.0.0.1 unless they are meant to face the internet.
    • Tests the deploy script against a stubbed docker and asserts host state for each failure path, before it touches a real server.
    • Diagnoses failed, half-done, or "successful but down" deploys against a checklist of known failure patterns.

    What's inside

    • SKILL.md: core rules and workflow
    • 6 workflows: setup pipeline, write deploy script, test deploy script, prepare host, harden secrets, fix broken deploy
    • 9 references: ownership boundary, image tagging, Dockerfile patterns, workflow patterns, secrets scoping, rollback safety, host exposure, healthchecks, deploy smells
    • 7 templates: GitHub Actions workflow, deploy.sh, docker-compose.yml, multi-stage Dockerfile, app.env.example, nginx reverse proxy, host SETUP.md
    • 1 script: a deploy-script test harness with a built-in docker stub

    Frameworks & tools

    GitHub Actions, Docker, Docker Compose v2+, SSH, any container registry (GHCR, Docker Hub, others), nginx. Language-agnostic: Node, Go, Python, Rust, PHP and Java apps follow the same pipeline.

    Why this beats prompting it yourself

    It fixes the order of decisions (ownership boundary, then host inspection, then templates, then failure-path tests) and enforces rules generic answers miss: capture commands that can fail after host state changes so set -e cannot skip the rollback, verify the rollback itself, sync files one at a time, and report the real cause of a failure instead of the first error message.

    Use cases

    • First CI/CD pipeline for a side project on a $6 droplet.
    • Reviewing an existing deploy workflow before it causes an outage.
    • Finding out why a deploy "succeeded" while the site is down.
    • Moving secrets from repository-level to environment-scoped.
    • Preparing a new VM to receive containers.

    Known limitations

    Not for managed platforms that deploy themselves (Vercel, Netlify, Fly.io, Render, Railway, App Runner) or for Kubernetes, ECS or Nomad. It does not write application code or language-specific CI (test/lint matrices); it starts once there is an image to ship.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for DevOps & Cloud.

    Needs a Linux VM you can reach over SSH, with Docker and Compose v2+ installed (the host-prep workflow covers that). Not for managed platforms that deploy themselves (Vercel, Netlify, Fly.io, Render, Railway, App Runner) or for Kubernetes, ECS or Nomad. It does not write application code or language-specific CI (test/lint matrices); it starts once there is an image to ship.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 8 days ago

    Accounts
    GitHub
    Software
    DockerDocker Compose v2+BashA GitHub repository (GitHub Actions)SSH access to the target Linux VMPythonGit

    Permissions

    Terminal / Shell
    Network Access
    Read Files
    Write Files

    Allowed Hosts

    api.github.com

    File Scopes

    .github/workflows/**
    Dockerfile
    docker-compose.yml
    deploy/**
    *.env.example

    Shell, Read and Write are used to create the workflow, deploy script, compose file and Dockerfile in your repository, and to run the bundled test harness. The harness runs locally against a stubbed `docker` and makes no network calls. Network access is only used when you ask the agent to inspect your server over SSH with access you grant; the skill never contacts a host on its own.

    Listed8 days ago

    What's inside

    Frequently Asked Questions

    Any Linux VM you can SSH into, including DigitalOcean droplets, EC2, Hetzner and Contabo.

    Yes. The image is the interface, so the pipeline is the same for Node, Go, Python, Rust, PHP or Java. The Dockerfile reference has a per-language table for manifests and install commands.

    Yes. scripts/test-deploy-script.sh runs your deploy script against a fake docker and checks host state (tag, compose file, output) for 10 cases: the happy path and every failure path, including a rollback that itself fails.

    Adapted from its templates: a GitHub Actions workflow, a remote deploy script with rollback, a compose file, a multi-stage Dockerfile, an app.env.example, an nginx site file and a host SETUP.md runbook. It does not commit for you.

    No. It writes files and runs the local test harness. It only reads your host over SSH if you give the agent that access, and real deploys run from your own GitHub Actions workflow.

    No. It targets a single VM running Docker Compose. Vercel, Netlify, Fly.io, Render, Railway, App Runner, Kubernetes, ECS and Nomad are out of scope.

    New in DevOps & Cloud