Getting Started

  1. Install docker rollout
  2. Prepare your service
  3. Start all services
  4. Deploy your service without downtime
  5. Deployment script

Install docker rollout

docker rollout is a single bash script that lives in docker cli plugins directory. It does not require any additional dependencies to work. To install docker rollout:

  1. Create Docker cli plugins directory if it does not exist:

    mkdir -p ~/.docker/cli-plugins

  2. Download the docker rollout script to Docker cli plugins directory:

    curl https://raw.githubusercontent.com/wowu/docker-rollout/master/docker-rollout -o ~/.docker/cli-plugins/docker-rollout

    You can also download it manually from the latest release page, review the script content, and save it to ~/.docker/cli-plugins/docker-rollout.

  3. Make the plugin executable:

    chmod +x ~/.docker/cli-plugins/docker-rollout

  4. Verify that the plugin is available:

    docker rollout --help
#=> Usage: docker rollout [OPTIONS] SERVICE
#=> ...

Prepare your service

docker rollout requires a Docker Compose file to work. Traffic to your service must be handled by a reverse proxy with automatic service discovery like Traefik or nginx-proxy. Here is a sample Compose file with Traefik reverse proxy and a service:

services:
  my-app:
    image: my-app:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.entrypoints=web"
      - "traefik.http.routers.my-app.rule=Host(`my-app.example.com`)"

  traefik:
    image: traefik:v2.9
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"

Your service cannot expose any ports, use network_mode: host, or have a defined container_name. These options will prevent docker rollout from starting multiple instances of the same service.

Check out the Examples section for more sample Compose files.

Start all services

Firstly start all services. docker rollout will be used later to update the service.

docker compose up -d

Deploy your service without downtime

Now after modifying the service (e.g. changing the image, rebuiling the image, changing envionment variables) instead of running docker compose up -d to update the service without downtime run docker rollout:

docker rollout my-app

You can also specify the path to the Compose file with -f option, just like with docker compose:

docker rollout -f docker-compose.yml my-app

This command will scale the service to two instances, wait for the new container to be ready, and then remove the old container. If you run more that one instance of the service, for example using docker compose scale or replicas in the Compose file, docker rollout will scale the service to twice the current number of instances.

If your service has a healthcheck defined, docker rollout will wait for the new containers to become healthy before removing the old ones. Reverse proxy like Traefik or nginx-proxy will route traffic to the new container automatically, after it becomes healthy.

See CLI Options for the list of all available options.

Deployment script

The recommended way of using docker rollout is to put it in your deployment script. For example, here is a sample deployment script for a service that is updated by pulling the latest code from a git repository, building a new image, running database migrations, and deploying the new version:

# Download latest code
git pull
# Build new app image
docker compose build web
# Run database migrations
docker compose run web rake db:migrate
# Deploy new version
docker rollout web

Usually docker rollout <service-name> will be a drop-in replacement for docker compose up -d <service-name> in your deployment scripts.