Rolling updates in Docker - Commands & Configuration

Introduction

When you update an application running in Docker containers, you want to avoid downtime. Rolling updates let you replace old containers with new ones gradually, so your app stays available during the update.

When you want to update your web app without stopping all users at once

When you need to fix bugs or add features to a running service without downtime

When you want to test new versions of your app on a few containers before full rollout

When you manage multiple replicas of a service and want smooth transitions

When you want to keep your app running while updating its Docker image

Config File - docker-compose.yml

docker-compose.yml

version: '3.8'
services:
  webapp:
    image: my-app:1.0
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
    ports:
      - "8080:80"

This file defines a service named webapp running 3 copies (replicas) of the app.

The update_config section controls the rolling update: it updates one container at a time (parallelism: 1) and waits 10 seconds between updates (delay: 10s).

This setup ensures smooth updates without downtime.

Commands

This command deploys the stack named 'myapp' using the docker-compose.yml file. It starts the service with 3 replicas as defined.

Terminal

docker stack deploy -c docker-compose.yml myapp

Expected Output

Creating network myapp_default

Creating service myapp_webapp

→

-c - Specifies the compose file to use for deployment

This command lists all running services in the Docker swarm to verify the service is up.

Terminal

docker service ls

Expected Output

ID                  NAME                MODE                REPLICAS            IMAGE               PORTS

abc123def456        myapp_webapp        replicated          3/3                 my-app:1.0          *:8080->80/tcp

This command updates the running service to use the new image version 1.1. Docker performs a rolling update based on the update_config settings.

Terminal

docker service update --image my-app:1.1 myapp_webapp

Expected Output

myapp_webapp

overall progress: 3 out of 3 tasks

1/3: running   [==================================================>]

2/3: running   [==================================================>]

3/3: running   [==================================================>]

verify: Service converged

→

--image - Specifies the new image to update the service with

This command shows the status of each task (container) in the service to confirm the update completed successfully.

Terminal

docker service ps myapp_webapp

Expected Output

ID                  NAME                IMAGE               NODE                DESIRED STATE       CURRENT STATE            ERROR               PORTS

xyz789abc123        myapp_webapp.1      my-app:1.1          node1               Running             Running 2 minutes ago

uvw456def789        myapp_webapp.2      my-app:1.1          node2               Running             Running 2 minutes ago

rst123uvw456        myapp_webapp.3      my-app:1.1          node3               Running             Running 2 minutes ago

Key Concept

If you remember nothing else from this pattern, remember: rolling updates replace containers one by one to keep your app running without downtime.

Common Mistakes

Updating the service image without defining update_config in the compose file

Docker updates all containers at once by default, causing downtime.

Set update_config with parallelism and delay to control the rolling update speed.

Using docker run instead of docker stack deploy for multi-replica services

docker run manages single containers and cannot perform rolling updates on multiple replicas.

Use docker stack deploy with a compose file defining replicas and update_config.

Not verifying the update status with docker service ps

You might miss failed updates or containers stuck in error state.

Always check service tasks status after update to confirm success.

Summary

Define your service with multiple replicas and update_config in docker-compose.yml for rolling updates.

Deploy the stack with docker stack deploy to start the service.

Update the service image with docker service update to trigger a rolling update.

Check the update progress and status with docker service ls and docker service ps.