Operating System CoreOS

How to Install Docker Compose on Flatcar Container Linux (CoreOS Successor)

CoreOS Container Linux is end of life. Install Docker Compose on its maintained fork, Flatcar Container Linux, as a CLI plugin or as a system extension image.

This guide shows two ways to add Docker Compose to Flatcar Container Linux: as a Docker CLI plugin in your home directory, which takes a minute on a running machine, and as a system extension image that is provisioned with the machine and updated automatically. Both respect the read-only /usr partition.

The original CoreOS Container Linux reached end of life on 26 May 2020 and receives no updates. Flatcar Container Linux is the maintained fork and behaves the same way for this task; Fedora CoreOS is the official successor from Red Hat and is a different, rpm-ostree based system. If you still run a CoreOS Container Linux machine, migrate it before adding more software to it.

Why the normal instructions do not work

Flatcar ships Docker in the base image but has no package manager, and /usr is an immutable, read-only partition that is swapped as a whole on every operating-system update. The usual plugin locations such as /usr/local/lib/docker/cli-plugins and the repository packages that Docker documents for Ubuntu or RHEL are therefore not available. You have two writable alternatives: your home directory, and system extension (sysext) images, which overlay extra files onto /usr at boot.

Also note that Compose is now a Docker CLI plugin called with docker compose (with a space). The standalone docker-compose binary is a legacy install method that Docker keeps only for backward compatibility.

Requirements

  • A Flatcar Container Linux machine, logged in as the default core user.
  • Docker working: docker info should print server details.
  • Outbound HTTPS access to github.com.

Method 1: Install the Compose plugin in your home directory

Docker looks for CLI plugins in ~/.docker/cli-plugins, and home directories are on the writable root filesystem, so this is the documented manual install without any change. Pick the release you want from the Compose releases page; v5.7.1 was the latest when this guide was written.

COMPOSE_VERSION=v5.7.1
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose

On an ARM64 machine, replace x86_64 with aarch64. Each release publishes a checksum file next to the binary; verify the download before you make it executable:

cd $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-x86_64.sha256 -o docker-compose.sha256
echo "$(cut -d' ' -f1 docker-compose.sha256)  docker-compose" | sha256sum -c -
rm docker-compose.sha256

The check must print docker-compose: OK. Then:

chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
docker compose version

The plugin is installed for the current user only. If you run Docker with sudo, the plugin is looked up in root's home directory instead, so either repeat the steps as root or run Docker as the core user. A plugin installed this way is not updated automatically: repeat the download with a newer version number when you want to upgrade.

If your scripts need the old docker-compose command

The same binary works as a standalone program. Flatcar keeps /opt writable, so /opt/bin is the place for it. Check that the directory is in your PATH first:

echo $PATH
sudo mkdir -p /opt/bin
sudo cp ~/.docker/cli-plugins/docker-compose /opt/bin/docker-compose
docker-compose version

If /opt/bin is not listed, add export PATH=$PATH:/opt/bin to ~/.bashrc. Prefer docker compose in anything new.

Method 2: Install Compose as a system extension

The Flatcar project builds a docker-compose sysext image in its sysext-bakery repository and publishes it at extensions.flatcar.org. Bakery extensions are community supported and, as the Flatcar documentation points out, not part of the release test suite, but they are the cleanest option when you provision many machines.

At provisioning time with Butane

Add the following to the Butane configuration of the machine. It downloads the image, links it into /etc/extensions so that it is merged at boot, and configures systemd-sysupdate to fetch newer versions:

variant: flatcar
version: 1.0.0
storage:
  files:
    - path: /opt/extensions/docker-compose/docker-compose-5.7.1-x86-64.raw
      mode: 0644
      contents:
        source: https://extensions.flatcar.org/extensions/docker-compose-5.7.1-x86-64.raw
    - path: /etc/sysupdate.docker-compose.d/docker-compose.conf
      contents:
        source: https://extensions.flatcar.org/extensions/docker-compose.conf
    - path: /etc/sysupdate.d/noop.conf
      contents:
        source: https://extensions.flatcar.org/extensions/noop.conf
  links:
    - target: /opt/extensions/docker-compose/docker-compose-5.7.1-x86-64.raw
      path: /etc/extensions/docker-compose.raw
      hard: false
systemd:
  units:
    - name: systemd-sysupdate.timer
      enabled: true
    - name: systemd-sysupdate.service
      dropins:
        - name: docker-compose.conf
          contents: |
            [Service]
            ExecStartPre=/usr/bin/sh -c "readlink --canonicalize /etc/extensions/docker-compose.raw > /tmp/docker-compose"
            ExecStartPre=/usr/lib/systemd/systemd-sysupdate -C docker-compose update
            ExecStartPost=/usr/bin/sh -c "readlink --canonicalize /etc/extensions/docker-compose.raw > /tmp/docker-compose-new"
            ExecStartPost=/usr/bin/sh -c "if ! cmp --silent /tmp/docker-compose /tmp/docker-compose-new; then touch /run/reboot-required; fi"

Transpile the file to Ignition JSON with the butane tool and pass the result to your provider as user data, the same way as any other Flatcar configuration. Ignition runs only on first boot, so this applies to new machines. When sysupdate has staged a newer image it creates /run/reboot-required; the new version becomes active after the next reboot. Set enabled: false on the timer if you prefer to control versions yourself.

On a machine that is already running

You can place the same image by hand, using the same paths as the Butane snippet, and reload the extensions:

sudo mkdir -p /opt/extensions/docker-compose
sudo curl -fsSL -o /opt/extensions/docker-compose/docker-compose-5.7.1-x86-64.raw https://extensions.flatcar.org/extensions/docker-compose-5.7.1-x86-64.raw
sudo ln -sf /opt/extensions/docker-compose/docker-compose-5.7.1-x86-64.raw /etc/extensions/docker-compose.raw
sudo systemctl restart systemd-sysext

List the merged extensions and test Compose:

systemd-sysext status
docker compose version

For ARM64, use the file name ending in -arm64.raw. The list of available versions is on the docker-compose page of the sysext bakery.

Verify with a small project

Create a throwaway project and start it:

mkdir ~/compose-test && cd ~/compose-test
cat > compose.yaml <<'EOF'
services:
  web:
    image: nginx:stable
    ports:
      - "8080:80"
EOF
docker compose up -d
curl -I http://127.0.0.1:8080

An HTTP/1.1 200 OK answer means Compose pulled the image and started the container. Clean up with:

docker compose down
cd ~ && rm -r ~/compose-test

Frequently asked questions

Does the plugin survive Flatcar updates?

Yes. An operating-system update replaces only the /usr partition. Files in your home directory, in /opt and in /etc/extensions are on the root filesystem and stay in place. What can change is Docker itself: after a major Docker update in a new Flatcar release, check that your Compose version is still recent enough.

Which method should I choose?

For one or two hand-managed servers, the home-directory plugin is the least effort and uses Docker's own release binaries. For fleets created from Butane or Ignition configuration, the sysext keeps machines identical and updates itself.

Can I run Compose from a container instead?

Older tutorials wrap the docker/compose image in a shell script. That image belongs to Compose v1, which is no longer developed, so do not use it. The plugin binary is a single static file and needs nothing else on the host.

What about Fedora CoreOS?

Fedora CoreOS is managed with rpm-ostree and its own Butane variant, so the sysext snippet above does not apply to it. The home-directory method relies only on Docker's plugin lookup in ~/.docker/cli-plugins and is the one to try there; check the Fedora CoreOS documentation for the container runtimes it currently ships.

Share story:

Continue reading other guides on How VPS.