Overview

An on-premises ClarityConnect deployment includes a helper container named Watchtower. Watchtower checks for new versions of the ClarityConnect and Redis containers and installs them automatically, so your connector stays current without manual work.

The Watchtower image in the original ClarityConnect docker-compose.yml (containrrr/watchtower) is no longer maintained. It does not work with Docker Engine 29 or later. After a Docker upgrade, the Watchtower container fails to start and logs an error similar to:

Error response from daemon: client version 1.25 is too old. Minimum supported API version is 1.44

A maintained version of the same tool (nickfedor/watchtower) is a drop-in replacement. It accepts the same settings, so the fix is a one-line change to your compose file.

Does this affect ClarityConnect itself?

No. ClarityConnect keeps running and processing while Watchtower is stopped. Only automatic updates are paused. We recommend making this change even if you have not upgraded Docker yet, so that a future Docker upgrade does not stop automatic updates.

Before you begin

• Access to the server (host) that runs ClarityConnect, with permission to run Docker commands.

• The location of your ClarityConnect docker-compose.yml file. Run all commands in this guide from that folder.

• Depending on your Docker version, the compose command is docker compose or docker-compose. Use whichever one works on your server.

Step 1: Back up your compose file

Make a copy of the current file so you can go back to it if needed:

cp docker-compose.yml docker-compose.yml.bak

Step 2: Change the Watchtower image

Open docker-compose.yml in a text editor and find the watchtower: section under services:. Change only the image: line, as shown below.

BEFORE
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - clarity_on_prem
    command: redis clarityconnect --interval 30 --include-stopped --revive-stopped --cleanup

AFTER
  watchtower:
    image: nickfedor/watchtower
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - clarity_on_prem
    command: redis clarityconnect --interval 30 --include-stopped --revive-stopped --cleanup

Leave the rest of the section as it is

Your command: line might not match the example exactly. For example, it might list clarityconnectoracle (this is a special oracle version). Keep your existing values and change only the image: line. YAML is sensitive to spacing, so keep the indentation exactly as it was. See below about changing the interval.

Step 3: Apply the change

You should now turn off your containers and restart them (this will pickup the changes to the docker-compose file

docker compose down
docker compose pull
docker compose up -d

Optional: Download the new Watchtower image and re-create the Watchtower container. This doesn't restart ClarityConnect or Redis.

docker compose pull watchtower

docker compose up -d watchtower

Optional: remove the old, unused image to free disk space:

docker image rm containrrr/watchtower

Step 4: Verify

1. Confirm that the Watchtower container is running. The STATUS column should show Up.

   docker ps --filter name=watchtower

2. Check the Watchtower logs. You should see startup messages and no “client version ... is too old” errors.

   docker logs --tail 50 watchtower

3. Confirm that the container uses the new image. The IMAGE column should show nickfedor/watchtower.

   docker ps --filter name=watchtower --format "{{.Names}} {{.Image}} {{.Status}}"

Does Watchtower update itself?

No. Watchtower checks only the containers named at the start of its command: line (redis, clarityconnect in the default file). Watchtower is not on that list, so it never checks for or installs new versions of itself. To pick up a newer Watchtower release later, run the two commands in Step 3 again.

To have Watchtower update itself automatically, see Optional: Allow Watchtower to update itself later in this guide.

Optional: Check for updates less often

By default, the ClarityConnect compose file tells Watchtower to check for updates every 30 seconds (--interval 30). That is about 2,880 checks per day for each container it watches.

Where those checks go depends on where each image is hosted:

• ClarityConnect images are hosted on Amazon Web Services (Amazon ECR Public). These checks are not affected by the limit described below.

• The redis image is hosted on Docker Hub. Docker Hub limits how many requests it accepts from users who aren't signed in, and it counts those requests per public IP address.

Watchtower's checks to Docker Hub are not signed in, so they count against your network's public IP address. All servers that share that outbound IP address share the same allowance. If the limit is exceeded, Docker Hub temporarily blocks checks for new container versions from that IP address. This can affect other systems on your network that use Docker Hub.

Checking less often greatly reduces the number of requests. The trade-off is that new ClarityConnect versions take longer to be installed automatically.

Choose a frequency

* Per container that Watchtower watches.

If you're not sure which to choose, every hour is a good balance between staying current and staying well under Docker Hub's limit.

Option: Change the interval

In the watchtower: section, change the number after --interval. The value is in seconds. This example sets it to once an hour:

BEFORE
  command: redis clarityconnect --interval 30 --include-stopped --revive-stopped --cleanup


AFTER
  command: redis clarityconnect --interval 3600 --include-stopped --revive-stopped --cleanup

Apply the new frequency

Save the file, then re-create the Watchtower container:

docker compose up -d watchtower

Confirm the change with docker logs --tail 50 watchtower. The startup messages show when the next check is scheduled.

Optional: Allow Watchtower to update itself

By default, Watchtower doesn't update itself. It checks only the containers named at the start of its command: line (redis, clarityconnect in the default file). To have Watchtower keep itself up to date as well, add watchtower to that list.

Before you turn this on, consider the following:

More Docker Hub checks: The Watchtower image is hosted on Docker Hub, like Redis. Turning this on doubles the update checks that count against your public IP address's Docker Hub limit. If you turn this on, we recommend also reducing how often Watchtower checks for updates (see Optional: Check for updates less often section above).

New versions install automatically: If a new Watchtower release has a problem, it's installed without review. Automatic updates may stop until the issue is fixed by hand.

Step 1: Add watchtower to the command line

In the watchtower: section of docker-compose.yml, add watchtower after the last container name on the command: line. Leave the rest of the line as it is.

BEFORE
   command: redis clarityconnect --interval 30 --include-stopped --revive-stopped --cleanup

AFTER
   command: redis clarityconnect watchtower --interval 30 --include-stopped --revive-stopped --cleanup

Keep your existing values

Your command: line might not match this example exactly. Keep your existing container names and settings, and add only the word watchtower before the first option that starts with --.

Step 2: Apply the change

Save the file, then re-create the Watchtower container:

docker compose up -d watchtower

Step 3: Verify

Confirm that Watchtower is running and its logs show no errors:

docker ps --filter name=watchtower

docker logs --tail 50 watchtower

When a new Watchtower version is available, Watchtower starts a new copy of itself and removes the old container. The --cleanup option also removes the old image. You might see the Watchtower container restart when this happens. This is expected.

To turn self-updates off, remove watchtower from the command: line and run docker compose up -d watchtower again.

Need Help?