Deploying a Containerized Backend to a VPS with Docker Compose + GitHub Actions (A Beginner's Runbook)

This is a complete, copy‑pasteable guide for shipping a backend app to a single Linux server using Docker Compose , with a GitHub Actions pipeline that builds the image, scans it, and deploys it over SSH. It is written to be language- and framework-agnostic . The examples use a Node/TypeScript API with PostgreSQL, Redis, and a background worker, but the same shape works for Python/Django, Go, Java/Spring, Ruby, etc. Anywhere you see your-app , your-org , your-server-ip , or example.com , substitute your own values. Every file is included in full, and every non-obvious line is explained. The last section — Common errors and how to fix them — is the part most guides skip, and it is the part that will actually save your afternoon. All of it comes from a real deployment, mistakes included. 1. The mental model (read this first) Before any YAML, understand the shape of what we're building. There are only three places anything lives: Your Git repository the single source of truth. Your code, your Dockerfile , your docker-compose.prod.yml , and your CI/CD workflows all live here. You only ever edit things here. A container registry (we use GHCR, GitHub's built-in registry) — a warehouse for the built application image. CI builds the image and pushes it here. Your server (a plain Linux VPS) pulls the image from the registry and runs it. It holds exactly two files: the compose file (copied from your repo by the pipeline) and a secrets file ( .env ) that never leaves the server. The flow, end to end: You push to main │ ▼ GitHub Actions: build image ──► push to registry ──► scan image │ ▼ GitHub Actions: SSH to server ──► pull image ──► run migrations ──► start app ──► health-check The single most important rule: the server is disposable . You never hand-edit files on the server, because the pipeline overwrites them from the repo on every deploy. If you fix something by editing on the server, the next deploy silently erases your fix. Edit in the repo, commit, push. (I learned t