Skip to main content

Quickstart Guide


logo.png GitHub-logo.png

 

 

Overview

A Docker swarm service for automatically updating your services whenever their base image is refreshed.
This Wiki Post will guide you through setting up Shepherd for Docker Swarm.

Usage

Docker CLI

docker service create --name shepherd \
  --constraint "node.role==manager" \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock,ro \
  containrrr/shepherd

Docker Compose

version: "3"
services:
  shepherd:
    image: containrrr/shepherd
    environment:
      TZ: 'US/Eastern'
      SLEEP_TIME: '5m'
      FILTER_SERVICES: ''
      VERBOSE: 'true'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    deploy:
      placement:
        constraints:
          - node.role == manager

How does it work?

Shepherd triggers updates by updating the image specification for each service, removing the current digest. Docker resolves the image tag, checks the registry for a newer version, and updates running container tasks as needed. Docker handles rolling updates, minimizing downtime for replicated services.

 

Configuration / Environment Variables

Below is a table of environment variables used for configuring Shepherd:

Environment Variable Description Example Value
SLEEP_TIME Time interval between update checks (default: 5 minutes) 5m
IGNORELIST_SERVICES Space-separated list of services to ignore during updates shepherd my-other-service
FILTER_SERVICES Filter for specifying services to update (matches docker service ls filter) label=com.mydomain.autodeploy
ROLLBACK_ON_FAILURE Roll back a service to the previous version if an update fails true
UPDATE_OPTIONS Additional options for the docker service update command --update-delay=30s
TIMEOUT Timeout for the docker service update process (default: 5 minutes) 300
APPRISE_SIDECAR_URL URL for the Apprise sidecar service to enable update notifications apprise-microservice:5000
IMAGE_AUTOCLEAN_LIMIT Enable old image autocleaning on service update 5
RUN_ONCE_AND_EXIT Run Shepherd once and then exit true
WITH_REGISTRY_AUTH Enable private registry authentication true
REGISTRY_USER / REGISTRY_PASSWORD Credentials for private registry authentication user123 / secret_password
REGISTRIES_FILE Path to the secret file containing multiple registry authentication entries /var/run/secrets/shepherd-registries-auth
WITH_INSECURE_REGISTRY Enable connection to an insecure private registry true
WITH_NO_RESOLVE_IMAGE Prevent pulling images from the registry true
TZ Set the timezone for log entries Europe/Zurich

 

Use Private Registry Authentication

Use Private Registry Authentication

You can enable private registry authentication by setting the WITH_REGISTRY_AUTH variable. Use REGISTRY_USER and REGISTRY_PASSWORD for a single registry. If using multiple accounts, create a secret file with the following format:

idregistryloginpassword

Example:

blog    registry.gitlab.com    gitlab+deploy-token-5123674    ssw2Nrd2

Create the Docker secret:

docker secret create shepherd-registries-auth private/shepherd-registries-auth

Then use the secret in your docker-compose.yml:

services:
  app:
    image: containrrr/shepherd
    environment:
      REGISTRIES_FILE: /var/run/secrets/shepherd-registries-auth
    secrets:
      - shepherd-registries-auth
secrets:
  shepherd-registries-auth:
    external: true

Add a label to specify the correct line from the secret file:

deploy:
  labels:
    - shepherd.enable=true
    - shepherd.auth.config=blog

Set WITH_INSECURE_REGISTRY to true to connect to an insecure private registry.

Set WITH_NO_RESOLVE_IMAGE to true to prevent pulling images from the

 

Back to top