Docker Compose Auto-Restart with Systemd Service

When to use

When a Docker Compose application (like a multi-container stack) needs to automatically restart after server reboot, preventing 503 errors from stopped containers while reverse-proxy (Apache, nginx) remains running.

Prerequisites

Docker and Docker Compose installed on the server
Docker Compose application defined in docker-compose.yml
Systemd available (Linux with systemd init system)
Application accessible via reverse proxy (Apache/nginx) on specific ports (e.g., 8001 for API, 3000 for web)

Steps

Create a systemd service file at /etc/systemd/system/docker-compose-ppt-tool.service:

[Unit]
Description=ppt-tool Docker Compose Service
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
WorkingDirectory=/path/to/ppt-tool
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
RemainAfterExit=yes
Restart=on-failure

[Install]
WantedBy=multi-user.target

Replace /path/to/ppt-tool with the actual directory containing docker-compose.yml
Reload systemd daemon:
```
sudo systemctl daemon-reload
```

Enable the service for auto-start:

sudo systemctl enable docker-compose-ppt-tool.service

Start the service:

sudo systemctl start docker-compose-ppt-tool.service

Verify containers are running:
```
docker compose ps
```

Key Configuration

WorkingDirectory: Must point to directory containing docker-compose.yml
Type=oneshot: Allows RemainAfterExit=yes to keep service marked as "started" even though process exits
Requires=docker.service / After=docker.service: Ensures Docker daemon starts before this service
ExecStart/ExecStop: Use full paths to docker-compose (/usr/bin/docker compose, not relative docker compose)

Gotchas

Server reboot stops containers but not Apache: Reverse proxy continues running, attempting to reach dead backend services → 503 errors
Relative docker-compose commands fail in systemd: Always use absolute path /usr/bin/docker compose in ExecStart/ExecStop
Verify docker.service exists: Check systemctl status docker.service before enabling the service
Postgres volumes persist: Data survives container restart; only application layer needs recovery
Port binding verification: After restart, confirm reverse proxy can reach containers on expected ports (8001, 3000, etc.)

Source

Project: ppt-tool

2.6 KiB Raw Blame History