Restart a dependent Compose app after an explicit backend restart

A Compose stack can be correct at startup yet become stale after maintenance. If an operator deliberately restarts a backend, the dependent app may continue running with an old socket, connection pool, cached credential, or other backend-facing process state.

More startup delays do not address that later lifecycle event.

Dependency-edge restart propagation

The implementation decision is to place restart propagation on the dependency edge. Configure the app with long-form depends_on for its backend and enable the dependency restart option there.

Keep that setting separate from each service's restart policy. A policy such as always or unless-stopped controls whether a service returns after its own container exits; it does not tell Compose to restart downstream services when a backend is intentionally restarted.

The inserted example models a backend and an app, then validates two pieces of declared intent:

• the requested operation is an explicit Compose restart of an existing dependency, and
• at least one dependent opts into restart propagation.

It also rejects the common but incomplete configuration where both services have restart policies but the dependency relationship has no propagation setting.

Expected behavior

Expected behavior is deliberately narrow. When Compose explicitly restarts the backend, it can restart the dependent app so the app gets a fresh process and can recreate backend-facing state.

If the application also needs to wait for real readiness on first boot, configure a health-based startup condition independently. Readiness answers when an app may begin; restart propagation answers what follows a later operator action.

Limitation

There is an important limitation: this is not a crash cascade. A backend that exits and is restarted automatically by the container runtime is not the same as an explicit Compose-managed restart. The rule also cannot be assumed when containers are restarted directly or by another tool.

Coordinated restarts are useful when needed, but resilient reconnect behavior inside the application remains the stronger long-term defense.

The example validates configuration and command intent only. Observing actual container lifecycle behavior requires a real Docker Compose engine.

Working example

export function buildBackendAppCompose() {
  return {
    services: {
      backend: {
        image: 'example/backend:1',
        restart: 'unless-stopped',
      },
      app: {
        image: 'example/app:1',
        restart: 'unless-stopped',
        depends_on: {
          backend: {
            condition: 'service_started',
            restart: true,
          },
        },
      },
    },
  };
}

/**
 * Validates the configuration and operation needed for Compose's documented
 * dependency-restart feature. This is a configuration check only: it does not
 * invoke Docker or prove that a live Compose engine restarted a container.
 */
export function validateExplicitDependencyRestart(compose, command) {
  if (!compose || typeof compose !== 'object' || !compose.services) {
    throw new TypeError('compose.services is required');
  }
  if (!Array.isArray(command) || command.length !== 4) {
    throw new TypeError('command must be: docker compose restart <dependency>');
  }
  const [docker, composeCommand, restart, dependency] = command;
  if (docker !== 'docker' || composeCommand !== 'compose' || restart !== 'restart') {
    throw new TypeError('command must be: docker compose restart <dependency>');
  }
  if (!compose.services[dependency]) {
    throw new RangeError(`dependency service "${dependency}" does not exist`);
  }
  const dependents = Object.entries(compose.services)
    .filter(([, service]) => service.depends_on?.[dependency]?.restart === true)
    .map(([name]) => name);
  if (dependents.length === 0) {
    throw new Error(
      `No service declares depends_on.${dependency}.restart: true; a container restart policy alone does not configure dependency restart propagation`,
    );
  }
  return {
    operation: 'explicit-compose-restart',
    dependency,
    dependents,
    proofBoundary: 'This validates declared Compose configuration only. Run Docker Compose against a real engine to observe container restarts.',
  };
}

Read the full article: https://chriseugenerodriguez.com/blog/restart-compose-app-when-dependency-restarted