How to Use Docker Rollout for Zero Downtime Deployment

Dissecting the Concept: How Does Docker Rollout Work?

Stage 1: Docker Rollout Plugin Installation

# 1. Create a directory for the Docker CLI plugin if it doesn't already exist
mkdir -p ~/.docker/cli-plugins

# 2. Download the latest version of the docker-rollout script from GitHub
curl https://raw.githubusercontent.com/wowu/docker-rollout/main/docker-rollout -o ~/.docker/cli-plugins/docker-rollout

# 3. Give the script execution (executable) permissions
chmod +x ~/.docker/cli-plugins/docker-rollout

docker rollout --help

Phase 2: Case Study - Deployment API (Golang + PostgreSQL)

1. Preparation of Reverse Proxy (nginx-proxy)

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
    networks:
      - web-network

networks:
  web-network:
    external: true

2. Refactor Application Configuration Files

# docker-compose.yml (For Applications)
services:
  api:
    image: my-registry.com/pos-api:latest
    # ANTI-PATTERN DOCKER ROLLOUT:
    # container_name: pos-api-1 (DELETE THIS)
    # ports: (DELETE THIS)# - "8080:8080"
    expose:
      - "8080"
    environment:
      - VIRTUAL_HOST=api.notopos.id
      - VIRTUAL_PORT=8080
      - DB_HOST=postgres
    networks:
      - web-network
      - db-network
    # MANDATORY: Healthcheck
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 10s

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_PASSWORD=secret
    networks:
      - db-network
    volumes:
      - pgdata:/var/lib/postgresql/data

networks:
  web-network:
    external: true
  db-network:

volumes:
  pgdata:

1. Deletion container_name: Docker Rollout must run 2 containers at once during transition. If the name is hardcoded, a conflict will occur. Docker Rollout will automatically rename the containers to [project]-api-1 and [project]-api-2.
2. Removal of ports and Use of expose: Just like names, host ports cannot be used simultaneously. We only exposeexpose port 8080 into internal networkDocker.
3. Environment VIRTUAL_HOST: This is magic variable captured by nginx-proxy.
4. Presence healthcheck: This is the "soul" of zero downtime. Docker Rollout will hold the execution of deleting old containers until endpoint /health consistently returns an HTTP status of 200.

3. Deployment Execution with Docker Rollout

# 1. Pull the latest image from the registry
docker compose pull api

# 2. Do a rolling update specifically for the "api" service
docker rollout api

Scaling service api to 2 instances...
Waiting for container project-api-2 to become healthy...
Container project-api-2 is healthy!
Stopping old container project-api-1...
Removing old container project-api-1...
Rollout completed successfully!

Stage 3: "How to Solve" - Solving Problems (Troubleshooting Playbook)

Problem 1: Request Disconnects Suddenly in the Middle of Transition (Active Connection Drop)

 labels:
      docker-rollout.pre-stop-hook: "touch /tmp/drain && sleep 15"

http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    // If drain file exists, return HTTP 503 (Unhealthy)
    if _, err := os.Stat("/tmp/drain"); err == nil {
        w.WriteHeader(http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
})

Issue 2: Database Migration Locking

1. Separate execution: Database migration should not be executed inside the application container (via entrypoint). Use a separate container or run it before rollout.
   
   
   Bash

   docker compose run --rm api migrate up
   docker rollout api
   

   ->
2. Backward Compatibility Rules: Your database schema should always support 2 code versions simultaneously (N and N-1).
   
   
   • If you want to delete a column, release new code that stops reading/writing that column first (Deploy 1).
   • After the old container dies, then do a migration release that drop that column (Deploy 2).
   • Never rename a column directly.Create a new column, copy the data, read/write from 2 columns, then gradually delete the old column.

Issue 3: Rollout Stuck (Timeout / Infinite Wait)

• Healthcheck URL is incorrect or requires authentication.
• Application crashes when booting (e.g. due to loss of Environment New variable), so it never reaches the Healthy state.

1. New Container Investigation: Do not stop the rollout process yet. Open a new terminal and check the log of the container being booting:
   
   
   Bash

   docker logs project-api-2 -f
   

   ->
   Look for stack trace or errors that cause the API to fail to run.
2. Set Parameters start_period: If your application is a giant Spring Boot Java-based application or a large PHP monolith that takes 30-40 seconds for initial initialization, increase the start_period in your docker-compose.yml file (e.g. start_period: 60s).
3. Configure Rollout Timeout: By default, docker rollout waits 60 seconds. You can extend the time tolerance via the -t:
   parameter
   
   Bash

   docker rollout api -t 120
   

   ->

Problem 4: Port Conflict Due to Hardcoded Ports in Codebase

Conclusion

1. Stateless Containers: Avoid storing asset files or sessions inside file system container (use S3 bucket or Redis).
2. Dynamic Reverse Proxy: Traefik or Nginx-Proxy is a mandatory companion so that new container internal IPs can be detected automatically.
3. Accurate Healthcheck: Don't just rely on checking ping.Make sure your application's endpoint /health actually checks for database connection readiness and cache before responding with the status 200 OK.