The Shepherd documentation leaves much to be desired so here is a rundown of what will need to be setup in order to update containers with Shepherd.

Here is a diagram of the disposition of the containers, where "shepherd" is the container that will update containers "A", "B", "C", etc.

Note that all containers will have to be updated in order to label them for update with their respective registry.

Shepherd supports authenticating to multiple repositories which is particularly useful in case local or third-party repositories must be pulled. Even if you do not use multiple registries, it is still a good idea to set up the configuration similar to what is described on this page in order to allow scaling up at a later point in time; besides, having an authentication file (or using Docker secrets) for all registries to connect to seem like the canonical way to go.

In order to authenticate and use multiple registries, a volume is mapped into the shepherd container:

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /local/path/to/shepherd/secrets:/secrets

where:

• /local/path/to/shepherd/secrets is the path to a directory on the host filesystem that will contain the credential file to be read in by the guest shepherd container

The REGISTRIES_FILE environment variable is set to point to a file containing credentials within the volume:

    environment:
      - REGISTRIES_FILE=/secrets/shepherd-registries-auth

where:

• /secrets/ is a bind-mount from the host

The credentials file will thus be placed on the host, following the example, at /local/path/to/shepherd/secrets, and is supposed to have the following format:

ID<TAB>REGISTRY_URL<TAB>USERNAME<TAB>PASSWORD<LF>

where:

• <TAB> is a tab space created by pressing the Tab key,
• ID is an identifier for the docker registry used only locally to refer to the registry from docker and can be comprised of any string,
• REGISTRY_URL is the official URL of the registry,
• USERNAME and PASSWORD are log-in credentials for the registry at REGISTRY_URL,
• <LF> is a line-feed (or newline, \n)

Here is an example credentials file that uses the docker.io registry and a local registry:

docker    index.docker.io    me    mypassword
local     docker.local:5000  sys   admin

Note that docker and local are just arbitrary labels that do not carry any particular meaning applicable to the docker registry being configured.

All containers will have to be labelled such that shepherd knows which repository to use. For example, given the secrets file:

docker    index.docker.io    me    mypassword
local     docker.local:5000  sys   admin

all the containers that are using images from index.docker.io must have the following added to their configuration:

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

and conversely, all the images that are using the local repository at docker.local:5000 must have the following added to their configuration:

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

Some sample files are provided in this section that should be ready-to-go and contain only minimal local information.

version: '3.9'

services:
  shepherd:
    image: containrrr/shepherd:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /local/path/to/shepherd/secrets:/secrets
    environment:
      - REGISTRIES_FILE=/secrets/shepherd-registries-auth
      - WITH_INSECURE_REGISTRY=true
      - WITH_REGISTRY_AUTH=true
      - IMAGE_AUTOCLEAN_LIMIT=1
      - TZ=Etc/UTC
    deploy:
      labels:
        - shepherd.enable=true
        - shepherd.auth.config=docker
      replicas: 1
      placement:
        constraints:
          - node.role == manager

From the previous section, the credentials file is created at /local/path/to/shepherd/secrets/shepherd-registries-auth with the following contents:

docker    index.docker.io    me    mypassword
local     docker.local:5000  sys   admin

Using image a from the docker repository with URL index.docker.io.

version: "3.8"

services:
  distcc:
    image: a:latest
    deploy:
      labels:
        - shepherd.enable=true
        - shepherd.auth.config=docker

And image b from the local repository local with the URL docker.local:5000:

version: "3.8"

services:
  distcc:
    image: docker.local:5000/b:latest
    deploy:
      labels:
        - shepherd.enable=true
        - shepherd.auth.config=local