- Home
- Skills
- DevOps & Cloud
- Docker Deploy to VPS with Auto-Rollback (GitHub Actions)
Works with the AI Agents you already use
Docker Deploy to VPS with Auto-Rollback (GitHub Actions)
Generic prompting writes the happy path and none of the failure paths.
$12
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 workflowDockerfile,.dockerignore,.gitignoredeploy/docker-compose.yml: the service definition the droplet runsdeploy/deploy.sh: the script that runs on the droplet, including rollbackdeploy/app.env.example: template for the secrets filedeploy/nginx/notes-api.conf: nginx site file for notes-api.example.comdeploy/SETUP.md: setup steps and runbook for the dropletdeploy/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 tomain, and manual dispatch. - Build job, every run:
- Checks that the compose
image:line equalsghcr.io/<owner>/<repo>in lowercase, and fails with the exact expected line if it doesn't. - Runs
bash -nandshellcheckondeploy.sh. - Runs the harness.
- Builds the image for
linux/amd64.
- Checks that the compose
- 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_ENABLEDis'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 droplet | Written by |
|---|---|
/opt/notes-api/docker-compose.yml | CI 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/.env | CI on every deploy. It holds TAG= and nothing else |
/opt/notes-api/app.env | Only you, by hand: chmod 600, never in git, CI never touches it |
/etc/nginx/sites-available/notes-api | Only you, by hand. The copy in git is for reference |
deploy.sh | Never 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 fromdocker/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-levelSSH_*secret with the same name exists, in which case it would quietly deploy to that host. Rungh secret listfirst and delete any leftovers.
- If one is missing, or the
- 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 atfalse.
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:8000only, 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, becausemain.pydoesn'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 -nandsh -nondeploy.shboth pass.docker compose config -qon 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.
shellcheckandactionlintaren't installed here. The CI step assumesubuntu-latestshipsshellcheck.- 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) andpython:3.14-slimwere 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
listenline stage 2 uses - swap, ufw state, any existing
daemon.json - x86_64 architecture
- that the SSH user's shell is bash
/healthzdoesn't touch the database, so a wrongDATABASE_URLstill deploys as healthy.- The SSH step doesn't pin the host key.
appleboy/ssh-actionsupports afingerprint:input if you want that.
By hand before the first deploy (details in deploy/SETUP.md)
- Set
image:indeploy/docker-compose.ymltoghcr.io/<owner>/<repo>in lowercase. The build fails until you do. - On the droplet, run the read-only checks listed in
SETUP.md: port 8000,docker compose version,nginx -v, swap,uname -m. - Take a backup. Add a 1 GB swapfile if there's none.
- Merge the Docker log-rotation settings into
daemon.jsonrather than overwriting it. - Create the
deployuser in thedockergroup and/opt/notes-apiowned by it. - Type
app.envon the droplet (chmod 600). - Generate the CI key on your machine and add its public key to
~deploy/.ssh/authorized_keys. - In GitHub, create the
productionenvironment, add its 3 secrets, and setDEPLOY_ENABLED=false. - Point an A record at the droplet, then install nginx stage 1, then run
certbot certonly --webroot, then switch to stage 2. Usenginx -tbefore everyreload, and confirm the other site still answers each time. - Merge, watch the build pass, flip
DEPLOY_ENABLEDtotrue, and deploy. Then check thatss -tlnpshows127.0.0.1:8000, and thatnc -z <droplet-ip> 8000from outside the droplet fails. - Deploy twice, then push a commit that breaks
/healthzand 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, neverlatest, so rollback is a tag swap. - Scopes secrets with GitHub Environments and keeps them out of build args,
ENVand compose files. - Prepares a fresh VM in a safe order and binds ports to
127.0.0.1unless they are meant to face the internet. - Tests the deploy script against a stubbed
dockerand 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-stageDockerfile,app.env.example, nginx reverse proxy, hostSETUP.md - 1 script: a deploy-script test harness with a built-in
dockerstub
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.
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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
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
Requires
Permissions
Allowed Hosts
File Scopes
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.