Skip to content

Keep Your Docker Swarm Services Up-to-Date with Shepherd

Published by bobo on May 14, 2025

If you’ve been running a Docker Swarm cluster, you’ve probably realized there’s no built-in mechanism for keeping your services updated when their images change. That’s where Shepherd comes in—a lightweight tool from the creators of Watchtower, but made especially for Swarm. It keeps an eye on your running services and redeploys them when the image gets updated in your registry.

Let’s walk through how to set up Shepherd in your Swarm cluster and use it to keep your services fresh and shiny.

What You’ll Need

  • A Docker Swarm cluster (can be a single-node or multi-node setup)
  • Docker installed
  • Internet access to pull images

Step 1: Deploy Shepherd in Your Swarm

Shepherd runs as a global service so that it can observe all nodes in your cluster. Here’s a simple docker-compose.yml to deploy it:

version: '3.8'

services:
  shepherd:
    image: ghcr.io/containrrr/shepherd:latest
    deploy:
      mode: global
      placement:
        constraints: [node.role == manager]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SHEPHERD_LOG_LEVEL=info
      - SHEPHERD_POLL_INTERVAL=60s

Save that as shepherd-stack.yml and deploy with:

docker stack deploy -c shepherd-stack.yml shepherd

This sets up Shepherd to run on all manager nodes and poll your services every 60 seconds.

Step 2: Label Services to be Watched

By default, Shepherd doesn’t touch any services. You have to explicitly opt in by adding a label when you deploy them.

Here’s an example of a service you want Shepherd to monitor and auto-redeploy:

version: '3.8'

services:
  nginx:
    image: nginx:latest
    deploy:
      labels:
        - "shepherd.watch=true"
    ports:
      - 8080:80

Make sure the label is exactly:

shepherd.watch=true

That’s the trigger for Shepherd to monitor the service’s image and redeploy when it detects a newer one.

Example Stack Deployment

Let’s say you have a stack called web-stack with NGINX that you want Shepherd to manage:

version: '3.8'

services:
  nginx:
    image: nginx:latest
    deploy:
      labels:
        - "shepherd.watch=true"
      replicas: 2
    ports:
      - 80:80

Deploy it:

docker stack deploy -c web-stack.yml web

Now, whenever there’s a new nginx:latest image, Shepherd will notice and restart the service using the new image.

Monitoring Shepherd

You can check Shepherd’s logs using:

docker service logs shepherd_shepherd

You’ll see entries like:

Found update for nginx:latest
Redeploying service web_nginx

Or better yet, have a look at ghcr.io/sergi0g/cup a simple app that I have deployed to swarm and all it does is report in a browser if apps are up to date. This was very useful during Shephard troubleshooting.

Pro Tips

  • Use immutable image tags like myapp:2025.05.13 if you want more control over what gets updated.
  • Shepherd does not rebuild images—just watches for newer ones.
  • Works best when you have CI pipelines pushing fresh images regularly.

Clean Up

To remove Shepherd:

docker stack rm shepherd

Final Thoughts

Shepherd is a “set it and forget it” tool that takes the pain out of keeping your Docker Swarm services updated. It’s ideal for setups where you’re using :latest or rolling tags and want your containers to stay in sync with the image registry.

If you’re already using Swarm in your home lab or even a production microservices setup, this is one of those tools that’s worth adding to your stack.

Published inswarm apps