Docker v29 on VPS: migrate without breaking your stacks

On each VPS to audit, run the following two commands:

docker version --format '{{.Client.APIVersion}}'
docker version --format '{{.Server.APIVersion}}'

If the client version is below 1.44 and the daemon is running v29, you will get an error on the next commands. The 1.44 threshold is the minimum accepted by Docker Engine v29: a client compiled for 1.43 or earlier fails with Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client.

If both lines show 1.44 or higher, your client is compatible. Proceed to the next step.

The docker-compose command with a hyphen and the docker compose command without a hyphen are not the same thing. v1 is a standalone Python binary, v2 is a Go plugin integrated into the Docker CLI.

which docker-compose && docker-compose --version

If the command returns a path in /usr/local/bin/ or /usr/bin/ with a version 1.x.x, you have the deprecated standalone binary. After the Docker v29 update, this binary returns docker-compose: command not found if the package was removed, or the API error described above if it is still present.

docker compose version

If this command returns Docker Compose version v2.x.x, the v2 plugin is already present. Both can coexist temporarily, but the goal is to use only the v2 plugin.

apt remove docker-compose
apt install docker-compose-plugin

On a Debian or Ubuntu VPS using the official Docker Inc. repositories (download.docker.com), the docker-compose-plugin package is available without additional configuration. If apt remove docker-compose responds Package not found, the binary was installed manually: locate it with which docker-compose and delete the file.

Post-migration verification:

docker compose version
# Docker Compose version v2.36.0

The vast majority of docker-compose.yml files written for v1 work without modification with the v2 plugin. The only syntax breaks concern version: directives above "3.8" (ignored in v2, not blocking) and the --compatibility option (removed). Validate your existing files:

docker compose config

This command resolves environment variables, validates syntax, and displays the resolved configuration. An error-free output means your file is compatible.

If your team uses shell scripts with docker-compose (hyphen), add a compatibility alias in /etc/bash.bashrc on the VPS:

alias docker-compose='docker compose'

This alias does not fix scripts that call docker-compose in absolute in a cron or systemd service — audit those separately.

The good news: docker network works correctly with nftables. Inter-container traffic, NAT, and port exposure continue to work. What changes is the underlying tool that writes the rules.

docker network ls

Your existing bridge networks are still listed. To verify that a container is receiving traffic on the expected port, test directly:

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

If the response is correct, the Docker data plane works regardless of the backend.

The problem arises when a third-party script (monitoring, Ansible, UFW rules) inspects iptables to verify Docker rules are present:

iptables -L DOCKER 2>&1

With the nftables backend, this chain is empty or absent. The script returns an error while Docker works perfectly. This is not a Docker failure — your audit tool is no longer looking in the right place.

To inspect the actual rules:

nft list ruleset | grep -A 20 'docker'

If your monitoring scripts or Ansible playbooks check for Docker-specific iptables rules, adapt them to query nftables instead of inferring a failure.

docker info | grep 'Storage Driver'

On a VPS updated to v29 without configuration changes, you typically get Storage Driver: overlay2. The containerd store is opt-in on v29 — it is not enabled automatically. It will become the default on v30.

To enable the containerd store on v29 and prepare the migration before it is imposed in v30, add the following key to /etc/docker/daemon.json:

{
  "features": {
    "containerd-snapshotter": true
  }
}

Restart the daemon:

systemctl restart docker

Verification:

docker info | grep 'Storage Driver'
# Storage Driver: overlayfs

Note: existing images pulled under overlay2 remain available, but new layers are written in containerd format. If you need to revert, remove the key and restart — images in the new format will no longer be accessible without the containerd backend. This is why a snapshot before this step is recommended.

Cause: the docker-compose v1 standalone binary is still present and attempts to communicate with the v29 daemon.

Remedy:

apt remove docker-compose
apt install docker-compose-plugin
docker compose version

If the binary was installed manually (outside apt), find it:

which docker-compose
rm /usr/local/bin/docker-compose

Cause: the docker-compose package (v1) was removed during the update, and the v2 plugin was not installed.

Remedy:

apt install docker-compose-plugin

Then verify that your scripts calling docker-compose (with hyphen) now use docker compose (without hyphen), or set the system alias.

Cause: your script inspects the DOCKER chain in iptables, but Docker v29 with nftables no longer writes it there.

Remedy: replace the iptables check with an nftables check:

nft list ruleset | grep -c 'docker'

If the count is above zero, Docker rules are present in nftables. Or use docker network inspect bridge to verify the data plane state directly from Docker, without depending on the network backend.

Cause: Dockge 1.4.1 and earlier call API routes absent from Docker Engine v29.

Remedy:

cd /opt/dockge
docker compose pull
docker compose up -d

If the latest tag of the Dockge image is already at 1.4.2 or higher, this command suffices. Otherwise, edit your Dockge docker-compose.yml to point to the corrective version tag before relaunching.

Cause: on the first restart of dockerd in nftables mode, NAT rules are rewritten in the correct backend, but some distributions have a conflict between the iptables-legacy service and nftables that delays rule setup.

Remedy:

systemctl stop docker
systemctl disable iptables
systemctl start docker

Then verify containers are restarted (docker compose up -d) and ports are exposed (`docker ps --format 'table {{.Names}}\t{{.Ports}}').