Docker-Compose Restart Policies: Configuration Guide for Non-Swarm Environments

Overview of Docker-Compose Restart Policies

In containerized deployments, ensuring services automatically restart after abnormal termination is crucial for system availability. Docker-Compose, as a multi-container orchestration tool, provides flexible restart policy configuration options. However, significant differences exist in restart policy implementation across Docker-Compose versions, particularly in configuration approaches for Swarm versus non-Swarm environments.

Core Differences Between Version 2 and Version 3

Docker-Compose file format version 2 directly supports the restart keyword as a service-level configuration item. This option works in all deployment environments, including standalone deployments and Swarm clusters. Its syntax is straightforward, allowing developers to specify restart policies directly in service definitions.

version: '2'
services:
  web:
    image: apache
    restart: always

Version 3 introduces a more complex deployment configuration structure, positioning restart_policy as a sub-item of deploy configuration. This design reflects Docker's enhanced native support for Swarm mode but also adds configuration complexity. In non-Swarm environments, directly using restart_policy causes configuration validation errors since this option is only valid within the deploy context.

Correct Configuration Methods for Non-Swarm Environments

For users not requiring Swarm functionality, version 2's restart configuration remains the most direct and effective solution. This configuration supports multiple policy values: no (no restart), always (always restart), on-failure (restart on failure), and the on-failure:N format with retry counts.

When version 3 format is necessary, restart policies can be implemented by retaining the restart option at the service level. Although version 3 documentation primarily emphasizes deploy.restart_policy, the service-level restart option remains supported, demonstrating Docker-Compose's backward compatibility design.

version: '3'
services:
  my-service:
    restart: on-failure:5

Configuration Examples and Best Practices

The following complete Docker-Compose configuration examples demonstrate restart policy configurations for different scenarios:

# Version 2 configuration example
version: '2'
services:
  database:
    image: postgres:13
    restart: always
    environment:
      POSTGRES_PASSWORD: example
  
  webapp:
    image: nginx:alpine
    restart: on-failure:3
    ports:
      - "80:80"

# Version 3 configuration example (non-Swarm environment)
version: '3.8'
services:
  cache:
    image: redis:6
    restart: unless-stopped
    volumes:
      - redis-data:/data

volumes:
  redis-data:

In actual deployments, selecting appropriate restart policies based on service characteristics is recommended. Critical database services typically use always to ensure data consistency, while frontend web services might better suit on-failure policies to avoid infinite restart loops. Monitoring container restart counts and reasons is essential for troubleshooting, achievable through docker events or container logs.

Common Issues and Solutions

Developers frequently encounter these issues when using Docker-Compose restart policies:

1. Configuration Validation Errors: Incorrectly using restart_policy instead of restart in version 3 causes Unsupported config option errors. The solution involves checking Compose file version and adopting correct syntax.
2. Policies Not Taking Effect: Ensure the Docker daemon supports restart policies and verify container status via docker-compose ps.
3. Version Compatibility: Different Docker-Compose versions vary in restart policy support; consulting corresponding official documentation is advised.

By understanding Docker-Compose restart policy design principles and version differences, developers can more effectively configure fault recovery mechanisms for containerized applications, enhancing overall system reliability.