Struggling to automate Docker image deployments to your VPS after a CI build? This guide explores three battle-tested methods, from quick-and-dirty SSH scripts for personal projects to robust, pull-based agents and full-blown orchestration for production systems.

So, Your CI Build Passed. Now What? Deploying Docker to a VPS Without Losing Your Mind

I remember it like it was yesterday. 3 AM, a critical hotfix, and the CI pipeline glowed a beautiful, reassuring green. The build passed, the image was pushed to our registry. We all breathed a sigh of relief. Ten minutes later, the support channels lit up again—the bug was still there. We’d all celebrated the successful build but, in our tired state, someone forgot the final, manual step: to SSH into prod-api-01 and actually run docker pull and restart the container. It was a simple, stupid, and completely avoidable mistake that taught me a lesson I carry to this day: if a deployment has a manual step, it’s not a deployment, it’s a liability.

The Core of the Problem: Bridging the Gap

Let’s get one thing straight. This isn’t a complex technical problem; it’s a communication problem. Your CI server (like GitHub Actions, GitLab CI, Jenkins) finishes its job and effectively shouts into the void, “Hey, I made a new image, my-app:1.2.5!” Meanwhile, your VPS is just sitting there, completely oblivious, happily running my-app:1.2.4. The whole challenge is building a secure and reliable bridge to carry that message from the CI server to the VPS, telling it to wake up and pull the new code.

So, how do we build that bridge? I’ve seen it done a hundred ways, but they usually fall into one of three camps. Let’s walk through them, from the quick fix to the “we’re-running-a-real-business” solution.

Solution 1: The “Get ‘Er Done” SSH Push

This is the most direct approach. Your CI runner, fresh off a successful image push, opens an SSH connection directly to your VPS and runs the deployment commands itself. It’s brute force, but for a personal project or an internal tool, it works.

The logic is simple: the last step in your CI script is a command that executes a remote script on the target server.

How it looks in a CI pipeline (e.g., GitLab CI):

deploy_to_vps:
  stage: deploy
  image: alpine:latest
  before_script:
    - 'which ssh-agent || ( apk add --update openssh )'
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts
  script:
    - ssh myuser@my-vps.com "cd /home/myuser/app && docker-compose pull && docker-compose up -d"

A Stern Warning: This method requires you to store a private SSH key as a secret in your CI system. If that key is ever compromised, an attacker has direct access to your server. Make sure you use a dedicated, least-privilege SSH key for deployments and lock it down as much as possible (e.g., by restricting which commands it can run using authorized_keys). This is a hack, and you should treat it as such.

Pros & Cons

Pros	Cons
Conceptually simple and direct. No extra software needed on the VPS. Fast feedback loop; the CI job fails if the deployment fails.	Huge security risk: Your CI runner holds the keys to the kingdom. Brittle. Network hiccups can fail the whole pipeline. Doesn’t scale to multiple servers easily. You’re punching a hole *out* from your CI and *in* to your server, which network admins rightly despise.

Solution 2: The “Smarter Pull” with Agents & Webhooks

This is where we start thinking like architects. Instead of the CI server pushing commands, we flip the model. The VPS is now responsible for its own updates; it just needs a little tap on the shoulder to tell it *when* to check. This is a “pull-based” approach, and it’s fundamentally more secure and robust.

Option A: The Simple Webhook Listener

You run a tiny, lightweight web server on your VPS that does one thing: listen for an incoming HTTP request on a specific endpoint (e.g., /deploy-latest). When your CI job finishes, its last step is to send a curl request to that endpoint with a secret token. The web server validates the token and then executes a local deployment script.

Example: A tiny Flask app on your VPS

# deploy_listener.py on your VPS
from flask import Flask, request
import subprocess
import os

app = Flask(__name__)
# Get the secret token from an environment variable! Do not hardcode it.
SECRET_TOKEN = os.environ.get("DEPLOY_TOKEN")

@app.route('/deploy-latest', methods=['POST'])
def trigger_deploy():
    auth_header = request.headers.get('Authorization')
    if not auth_header or auth_header != f"Bearer {SECRET_TOKEN}":
        return "Unauthorized", 401

    try:
        # Run your deployment script locally
        subprocess.run(["/home/myuser/app/deploy.sh"], check=True)
        return "Deployment triggered successfully!", 200
    except subprocess.CalledProcessError as e:
        return f"Deployment failed: {e}", 500

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=9001)

CI job step:

notify_vps:
  stage: deploy
  script:
    - 'curl -X POST -H "Authorization: Bearer $DEPLOY_TOKEN_SECRET" http://my-vps.com:9001/deploy-latest'

Option B: The “Set and Forget” Agent (Watchtower)

This is my personal favorite for simple, single-VPS setups. You run a container on your VPS whose only job is to watch for new versions of your *other* containers. That’s it. My tool of choice here is Watchtower.

With this setup, your CI pipeline’s only job is to build the image and push it to the registry with a consistent tag (like latest or your branch name). Watchtower, running on your VPS, polls the registry every few minutes. When it sees the image checksum has changed, it automatically pulls the new image, gracefully stops the old container, and starts the new one with the exact same configuration. It’s magic.

How to run Watchtower on your VPS:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --interval 300 \
  my-app-container-name

Your CI pipeline now has no “deploy” step. It just builds and pushes. The deployment happens passively and automatically on the server.

Pro Tip: For private registries, you’ll need to provide Watchtower with your Docker registry credentials. Also, be mindful of the --interval. Polling every 5 minutes (300 seconds) is fine, but polling every 5 seconds is just going to get your IP banned by your registry provider.

Solution 3: The “Nuclear Option” with Orchestrators

Okay, so your project is growing. You’re not just running on one VPS anymore; you have prod-web-01, prod-web-02, and a worker node. The previous methods start to break down. This is where you graduate to a real container orchestrator like Kubernetes (or its simpler cousins K3s/K0s) or Docker Swarm.

This is a completely different paradigm. You are no longer telling a specific server what to do. Instead, you declare the desired state of your system in configuration files (YAML manifests), and the orchestrator works tirelessly to make reality match that state.

Your CI/CD pipeline’s role changes. It no longer touches your servers at all. Instead, it does one of two things:

1. Direct API Call: It uses a tool like kubectl or helm to tell the Kubernetes API, “Hey, for the ‘my-app’ deployment, I now want you to use the image my-repo/my-app:1.2.6“.
2. GitOps (The Real Pro Move): The CI pipeline builds the image and then updates a YAML file in a separate Git repository (your “config repo”). An agent running in your cluster (like ArgoCD or Flux) is constantly watching that repo. When it sees your change, it automatically applies it to the cluster. This gives you a perfect audit trail of every single change made to your infrastructure.

What the CI step might look like (GitOps example):

update_manifest:
  stage: deploy
  script:
    - git clone https://git-user:$GIT_TOKEN@my-git-server.com/ops/app-config.git
    - cd app-config
    # Use a tool like kustomize or sed to update the image tag
    - sed -i "s|image: my-repo/my-app:.*|image: my-repo/my-app:${CI_COMMIT_TAG}|g" deployment.yaml
    - git commit -am "Update image to ${CI_COMMIT_TAG}"
    - git push

Is this overkill? For a single blog on a $5 VPS, absolutely. It’s bringing a bazooka to a fistfight. But if you have any ambition for your application to scale, handle failure gracefully (e.g., a node goes down), and have zero-downtime deployments, then learning an orchestrator is not just a good idea—it’s an inevitability.

So, Which One Should I Choose?

As with all things in engineering, the answer is “it depends”.

• Is it a personal project or internal dev tool? The SSH Push is fine. Just be aware of the risks.
• Is it a single, important application on one or two servers? The Webhook or Watchtower approach is your sweet spot. I lean towards Watchtower for its sheer simplicity.
• Are you building a scalable, multi-service, production-grade system? Bite the bullet. It’s time to learn Kubernetes and GitOps. Start with K3s to ease the pain.

The goal is to get that last manual step out of your process. Your time is too valuable to be spent running manual deployment commands at 3 AM. Automate it, make it reliable, and get some sleep.

---

🤖 Frequently Asked Questions