Skip to main content

Upgrade and Version Management

Docker upgrades affect the daemon, CLI, Compose plugin, and containerd runtime. An unplanned upgrade can break running services even if your application code has not changed. This lesson covers how to upgrade safely with rollback preparation.

Check Your Current Versions​

Before upgrading, record your current baseline:

docker version
docker compose version
docker info | grep -E "Server Version|Storage Driver|Cgroup"

Save this output in your change notes. You will need it to compare with post-upgrade behavior and to roll back if something goes wrong.

Upgrade on Ubuntu / Debian​

Step 1: Update the Package Index​

sudo apt-get update

Step 2: Check Available Versions​

See what versions are available in the Docker repository:

apt-cache madison docker-ce

This shows all available versions. You can either upgrade to the latest or pin to a specific version.

Step 3: Upgrade to the Latest Version​

sudo apt-get install --only-upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 3 (Alternative): Pin to a Specific Version​

To install a specific version instead of the latest:

# List available versions
apt-cache madison docker-ce | head

# Install a specific version (example)
VERSION_STRING=5:24.0.7-1~ubuntu.22.04~jammy
sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

Step 4: Verify​

docker version
docker compose version
docker ps

Upgrade on RHEL / CentOS / AlmaLinux​

Step 1: Check Available Versions​

yum list docker-ce --showduplicates | sort -r | head

Step 2: Upgrade​

sudo yum update docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Step 2 (Alternative): Pin to a Specific Version​

sudo yum install docker-ce-<VERSION> docker-ce-cli-<VERSION> containerd.io docker-buildx-plugin docker-compose-plugin

Step 3: Restart and Verify​

RHEL-based upgrades may require a daemon restart:

sudo systemctl restart docker
docker version
docker ps

Pre-Upgrade Checklist​

Before upgrading on a production server, complete this checklist:

# 1. Record current versions
docker version > /tmp/docker-pre-upgrade.txt
docker compose version >> /tmp/docker-pre-upgrade.txt

# 2. List running containers
docker ps >> /tmp/docker-pre-upgrade.txt

# 3. Back up compose files and environment files
cp compose.yaml compose.yaml.pre-upgrade
cp .env .env.pre-upgrade 2>/dev/null

# 4. Back up daemon configuration
sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.pre-upgrade

# 5. Ensure volume backups are current
docker volume ls

Post-Upgrade Verification​

After upgrading, verify both Docker platform health and application health:

# Platform checks
sudo systemctl status docker
docker version
docker compose version
docker info

# Workload checks
docker ps
docker compose ps
docker logs --tail=50 <critical-container>

If you have application health endpoints, test those too:

curl -s http://localhost:8080/health

Rolling Back an Upgrade​

If the upgrade causes problems, downgrade to the previous version:

On Ubuntu / Debian​

# Install the specific previous version
VERSION_STRING=5:24.0.6-1~ubuntu.22.04~jammy
sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io

# Restart and verify
sudo systemctl restart docker
docker version
docker ps

On RHEL / CentOS​

sudo yum downgrade docker-ce docker-ce-cli
sudo systemctl restart docker
docker version

Restore Configuration if Needed​

sudo cp /etc/docker/daemon.json.pre-upgrade /etc/docker/daemon.json
sudo systemctl restart docker

Version Pinning to Prevent Accidental Upgrades​

After installing the version you want, you can hold (pin) Docker packages so they are not accidentally upgraded during system updates.

On Ubuntu / Debian​

# Hold Docker packages
sudo apt-mark hold docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Later, to allow upgrades again
sudo apt-mark unhold docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

On RHEL / CentOS​

Add exclude=docker-ce* to your /etc/yum.conf to prevent automatic upgrades, or use the versionlock plugin:

sudo yum install yum-plugin-versionlock
sudo yum versionlock docker-ce docker-ce-cli containerd.io

Key Takeaways​

  • Always record your current Docker versions before upgrading.
  • Back up compose files, environment files, and daemon.json before making changes.
  • Use apt-cache madison or yum list --showduplicates to see available versions.
  • Pin Docker packages after installing the version you want to prevent accidental upgrades.
  • Test upgrades in a non-production environment first when possible.
  • Know how to downgrade -- have the previous version string ready before you start.

What's Next​