Linked Containers

Overview

Watchtower, by default, ensures that interdependent containers are updated in the correct order to maintain application stability. It automatically detects container dependencies through various mechanisms and uses topological sorting to determine the optimal update sequence.

When containers depend-upon each other (such as a web application depending on a database), updating them in the wrong order can cause service disruptions.

Watchtower addresses this by:

• Detecting dependencies through Docker links, labels, and network configurations
• Performing topological sorting to determine the correct update order
• Stopping containers in reverse dependency order (dependents first - i.e., web app before database)
• Restarting containers in dependency order (dependencies first - i.e., database before web app)

This ensures that dependent services are stopped before their dependencies are updated, and dependencies are available when dependents restart.

How It Works

Dependency Detection

Watchtower detects container dependencies through multiple mechanisms, checked in the following priority order:

1. Watchtower depends-on label (com.centurylinklabs.watchtower.depends-on)
2. Docker Compose depends_on label (com.docker.compose.depends_on)
3. Docker links and network mode (legacy Docker linking and network_mode: service:container)

Watchtower Depends-On Label

The com.centurylinklabs.watchtower.depends-on label allows explicit declaration of dependencies:

LABEL com.centurylinklabs.watchtower.depends-on="database,redis"

This label accepts a comma-separated list of container names that must be available before this container starts. This supports referencing containers from other Docker Compose projects or stacks, enabling cross-project dependency management.

Docker Compose Depends-On Label

Watchtower automatically recognizes Docker Compose’s depends_on relationships:

services:
  web:
    image: nginx
    depends_on:
      - database
  database:
    image: postgres

The com.docker.compose.depends_on label is automatically set by Docker Compose and parsed by Watchtower to extract service names and support implicitly restarting linked services.

services:
  web:
    depends_on:
      database:
        condition: service_healthy
        restart: true

Docker Links and Network Mode

For legacy Docker setups using links or network_mode: service:container, Watchtower treats these as implicit dependencies:

# Container with explicit link
docker run --link database:db nginx

# Container using service network mode
docker run --network container:database nginx

Topological Sorting

Watchtower uses topological sorting to determine the correct update order. This algorithm:

• Builds a dependency graph from all detected relationships
• Detects cycles (failing with a circular dependency error)
• Produces a linear ordering where dependencies precede dependents

Update Order

When updates are needed, Watchtower follows this sequence:

1. Identify all containers requiring updates
2. Expand the set to include all containers in the dependency chain
3. Sort containers using topological order (dependencies first)
4. Stop containers in reverse topological order (dependents first)
5. Update and restart containers in topological order (dependencies first)

This ensures that:

• Dependent services are stopped before their dependencies change
• Dependencies are fully restarted before dependents attempt to connect

Configuration

Automatic Detection

In most cases, no additional configuration is required. Watchtower automatically detects dependencies from:

• Docker Compose depends_on declarations
• Existing Docker links
• network_mode: service:container configurations

Disable Docker Compose Depends-On

If you want to disable automatic dependency detection from the Docker Compose depends_on configuration while preserving other dependency sources, use the following configuration:

services:
  watchtower:
    image: nickfedor/watchtower
    environment:
      - WATCHTOWER_USE_COMPOSE_DEPENDS_ON=false

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    nickfedor/watchtower \
    --use-compose-depends-on=false

This disables parsing of the com.docker.compose.depends_on label while still honoring:

• Watchtower’s explicit com.centurylinklabs.watchtower.depends-on label
• Legacy Docker links
• Network mode dependencies (network_mode: service:container)

Explicit Dependencies

For cases where automatic detection is insufficient, use the Watchtower depends-on label:

FROM nginx:latest

# Declare dependencies on database and cache services
LABEL com.centurylinklabs.watchtower.depends-on="postgres,redis"

services:
  web:
    image: nginx
    labels:
      - com.centurylinklabs.watchtower.depends-on=postgres,redis
  postgres:
    image: postgres
  redis:
    image: redis

Advanced Scenarios

Multiple Dependencies

LABEL com.centurylinklabs.watchtower.depends-on="database,cache,queue"

Complex Dependency Chains

services:
  web:
    image: nginx
    depends_on:
      - api
  api:
    image: myapi
    depends_on:
      - database
      - cache
  database:
    image: postgres
  cache:
    image: redis

In this scenario, Watchtower will update containers in the order: cache, database, api, web.

Examples

MySQL-WordPress Scenario

Consider a classic WordPress setup with MySQL database:

services:
  wordpress:
    image: wordpress:latest
    depends_on:
      - mysql
    environment:
      WORDPRESS_DB_HOST: mysql
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: example

Microservices Architecture

For complex applications with multiple services:

services:
  api-gateway:
    image: nginx
    depends_on:
      - auth-service
      - user-service
  auth-service:
    image: auth-service
    depends_on:
      - redis
  user-service:
    image: user-service
    depends_on:
      - postgres
  redis:
    image: redis
  postgres:
    image: postgres

postgres → user-service
redis → auth-service
auth-service → api-gateway
user-service → api-gateway

Legacy Docker Links

For applications using traditional Docker linking:

# Start database
docker run -d --name mysql mysql:8.0

# Start web app with link
docker run -d --name webapp --link mysql:db nginx

Network Mode Dependencies

Containers using network_mode: service:container:

services:
  sidecar:
    image: sidecar
    network_mode: service:main-app
  main-app:
    image: main-app

Troubleshooting

Common Issues

Updates Failing Due to Circular Dependencies

Solution: Review and remove circular dependencies. For example, if A depends on B and B depends on A, remove one of the dependencies or restructure your services.

Containers Not Updating in Expected Order

Check:

• Verify dependency labels are correctly formatted
• Ensure container names match exactly
• Check Docker Compose service names vs container names

Missing Dependencies

Symptoms: Containers update out of order or fail to connect after updates.

Debug: Enable debug logging to see detected dependencies:

watchtower --debug

Look for log messages like:

• “Retrieved links from watchtower depends-on label”
• “Retrieved links from compose depends-on label”
• “Completed dependency sort”

Debugging Commands

Enable verbose logging to inspect dependency detection:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --debug \
  --run-once

Check container labels:

docker inspect container_name | jq '.[0].Config.Labels'