systemd units for Compose stacks — boot ordering and the races · Docker & Containers

Docker’s restart policies already bring containers back after a reboot, so the first question is why you would involve systemd at all.

The answer is everything a restart policy cannot express: ordering against anything that is not Docker, dependency on a filesystem being mounted, a single command that stops the whole stack, failure surfaced through systemctl status and the journal, and a place for the operator to look that is the same place they look for every other service on the host.

The second question — and this is the one that produces 6am incidents — is what a unit has to say to survive a real reboot, as opposed to the systemctl restart you tested with.

What you are ordering against

Read the daemon’s own unit before writing anything that depends on it:

Read-only / Safedocker.service— The shipped unit, on Debian and Ubuntu.

$ systemctl cat docker.service

[Unit]
Description=Docker Application Container Engine
Documentation=https://docs.docker.com
After=network-online.target nss-lookup.target docker.socket firewalld.service containerd.service time-set.target
Wants=network-online.target containerd.service
Requires=docker.socket

[Service]
Type=notify
ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
TimeoutStartSec=0
Restart=always
Delegate=yes
KillMode=process

Illustrative output

Three lines matter for your unit:

Type=notify. The daemon tells systemd it is ready only once the API is actually serving. So After=docker.service is a real guarantee, not an approximation.
Requires=docker.socket with -H fd://. The daemon is socket activated. The socket exists before the daemon does.
Delegate=yes and KillMode=process. Containers live in cgroups that systemd has handed over to Docker. They are not in your unit’s cgroup, which has consequences we come back to below.

A unit that works

The oneshot pattern, annotated

# /etc/systemd/system/myapp.service
[Unit]
Description=myapp Compose stack
Requires=docker.service
After=docker.service
RequiresMountsFor=/srv/myapp/data
StartLimitIntervalSec=300
StartLimitBurst=3

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/srv/myapp
ExecStart=/usr/bin/docker compose up -d --wait
ExecStop=/usr/bin/docker compose down
ExecReload=/usr/bin/docker compose up -d --wait
TimeoutStartSec=900
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

Requires= and After= together. Requires= says “if docker fails, fail me too”. After= says “and start me second”. They are independent directives and you need both.
RequiresMountsFor= creates the dependency on whatever mount unit provides that path, and orders the unit after it.
Type=oneshot with RemainAfterExit=yes. docker compose up -d returns immediately; without RemainAfterExit the unit would be considered inactive the moment it returned.
--wait makes up block until every service is running or healthy, so the unit reaching active means something.
TimeoutStartSec=900 covers a cold-cache image pull. The default is 90 seconds.

Configuration changeinstall— Install and enable the unit.

systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/myapp.service
systemctl enable --now myapp.service
systemctl status myapp.service

systemd-analyze verify catches typos in directive names, which systemd otherwise logs as a warning at load time and then ignores — a misspelled RequresMountsFor= is a unit that has no mount dependency at all and looks completely normal.

The four races

Each of these works when you test it with systemctl restart and fails on a cold boot.

1. `Requires=` without `After=`

Without After=, systemd is free to start your unit in parallel with docker.service. The compose command runs before the API is up:

Aug 11 06:14:02 host docker[1841]: Cannot connect to the Docker daemon at
unix:///var/run/docker.sock. Is the docker daemon running?
Aug 11 06:14:02 host systemd[1]: myapp.service: Main process exited, code=exited, status=1

The confusing part is that it is intermittent. On a host with a fast disk the daemon wins the race and everything looks fine for months.

2. Bind mounts on a filesystem that is not mounted yet

This is the expensive one.

The empty data directory

A stack bind-mounts /srv/myapp/data, which is an NFS or iSCSI mount, or just a separate LVM volume. On boot, systemd starts myapp.service before srv-myapp-data.mount is ready. Docker finds no directory at that path, so it creates one — an empty directory on the root filesystem — and mounts that into the container.

The database starts, finds no data files, and initialises a brand new empty database. The application comes up looking perfectly healthy. Users report that all their data is missing.

The real data is still there, hidden underneath the mount point once the filesystem mounts. But the application has now been writing to the shadow directory, so recovery means stopping everything and reconciling two divergent datasets.

RequiresMountsFor=/srv/myapp/data prevents it. So does the belt-and-braces version: put the bind mount path check in the unit itself.

ExecStartPre=/usr/bin/test -f /srv/myapp/data/.mounted

with .mounted being a file that exists only on the real filesystem. A unit that refuses to start is infinitely cheaper than a database that starts empty.

3. `Type=oneshot` without `RemainAfterExit=yes`

docker compose up -d returns as soon as the containers are created. systemd sees the main process exit successfully and, for a oneshot unit without RemainAfterExit, marks the unit inactive (dead).

Consequences: systemctl status myapp shows inactive while the stack is running, ExecStop= never runs because there is nothing to stop, and systemctl stop myapp therefore leaves every container up. Operators conclude that systemd “is not managing it” and start running compose by hand alongside the unit, which is how a host ends up with two sources of truth.

4. Start and stop timeouts

TimeoutStartSec defaults to 90 seconds and TimeoutStopSec to 90 seconds:

Read-only / Safedefaults— The manager-wide defaults your unit inherits.

$ systemctl show -p DefaultTimeoutStartUSec -p DefaultTimeoutStopUSec

DefaultTimeoutStartUSec=1min 30s
DefaultTimeoutStopUSec=1min 30s

On the first boot after an image change, docker compose up -d --wait has to pull. A 900 MB image on a slow link takes longer than 90 seconds, systemd kills the start job, and with Restart=on-failure the unit loops — pulling, being killed, pulling again — saturating the link and never finishing.

The stop side is worse, because it is silent. docker compose down stops each container with its configured grace period. Four containers at 60 seconds each can exceed 90 seconds, systemd SIGKILLs the compose process mid-teardown, and you are left with half the stack running, orphaned networks, and a unit that reports it stopped cleanly.

Size both timeouts from the stack, not from the default.

Do not manage the same containers twice

What happens when a restart policy and a systemd unit both manage a stack?

At boot the daemon starts every container whose restart policy is always or unless-stopped — that happens inside docker.service, before your unit runs. Then your unit runs docker compose up -d, sees the containers already running with the right configuration, and does nothing. Harmless.

Now systemctl stop myapp runs docker compose down, which removes the containers. Also fine.

The failure is the ordering at shutdown. systemd stops units in reverse dependency order, so myapp.service stops before docker.service — correct, provided you wrote After=docker.service. Omit it and the ordering is undefined: docker.service may go down first, and docker compose down then fails to connect, times out, and the unit fails on every shutdown.

The other failure is a human one. Two mechanisms that both claim to start the stack mean nobody can answer “what starts this on boot” without reading both. Pick one:

Restart policies only, for a host with one stack and no ordering needs. Set restart: unless-stopped in the Compose file and stop there.
A systemd unit only, with restart: "no" in the Compose file, for anything that has to be ordered against a mount, a VPN, a network target, or another service.

Timers, not cron

For periodic Docker maintenance, a systemd timer beats a crontab: it logs to the journal, it has Persistent=true for missed runs, and systemctl list-timers shows the whole schedule on the host in one place.

# /etc/systemd/system/docker-prune.service
[Unit]
Description=Prune unused Docker build cache
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
ExecStart=/usr/bin/docker builder prune --force --filter 'until=168h'

# /etc/systemd/system/docker-prune.timer
[Unit]
Description=Weekly Docker build cache prune

[Timer]
OnCalendar=Sun 03:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target

RandomizedDelaySec matters as soon as you have more than one host: without it, every host in the estate prunes at exactly 03:00 and hits the registry or the storage backend simultaneously.

Read-only / Safelist-timers— Every scheduled job on the host, with its last and next run.

$ systemctl list-timers --all docker-prune.timer

NEXT                        LEFT     LAST                        PASSED  UNIT               ACTIVATES
Sun 2026-08-16 03:11:47 UTC 4 days   Sun 2026-08-09 03:23:05 UTC 2 days   docker-prune.timer docker-prune.service