Docker & Compose on Debian: Fix Deploy Issues for Fremantle Devs

If you run apps on Debian with Docker and Docker Compose—whether a side project, a small business stack, or a client site—failed deploys waste evenings and risk downtime. This guide is for Fremantle and wider WA developers and site owners who need clear, copy-pasteable fixes for the problems that actually show up in production, not generic “install Docker” fluff.

We cover real symptoms on Debian (Bookworm/Bullseye-style hosts), numbered DIY steps you can run over SSH, and when it is smarter to book a direct specialist. Fixwebnode provides remote help for Docker & Docker-Compose on Debian—streamlining app deployment without marketplace bidding or vague “someone will reply” queues.

Why Docker and Compose on Debian matter for local deploys

Debian is a solid base for long-running app hosts: predictable packages, stable kernels, and straightforward firewall tooling. Docker and Docker Compose let you ship multi-service apps (web, DB, cache, workers) with one compose file. When the daemon, networking, storage, or Compose project state drifts, you get opaque errors: containers that exit on start, ports that “belong” to nothing useful, or Compose that cannot talk to the engine at all.

For teams around Fremantle shipping over remote SSH, a clean install path and a short troubleshooting runbook cut mean-time-to-recovery. Below is the practical path Fixwebnode uses when diagnosing these stacks remotely.

Why can’t Docker Compose connect to the daemon on Debian?

Most “Cannot connect to the Docker daemon at unix:///var/run/docker.sock” failures mean the engine is stopped, the socket permissions exclude your user, or you are not in the docker group after install. Confirm the service is active, your user is in the group, and you have re-logged in—then retry Compose with the same user that owns the project.

Common issues with Docker and Compose on Debian

These problems are distinct: different root causes, different first commands. Match your symptom, then jump to the matching fix section.

• Daemon or socket access failure — Compose or CLI reports it cannot reach unix:///var/run/docker.sock; docker ps fails even as a normal user.
• Port already allocated on up — docker compose up -d stops with bind errors on 80, 443, 3306, or a custom app port.
• Containers exit immediately or never become healthy — status shows Exited (1) or healthchecks stay failing; app never answers on the published port.
• Disk fills with images, build cache, and anonymous volumes — deploys fail with “no space left on device”; / or Docker’s data root is near 100%.
• Broken Docker APT source or GPG after a Debian upgrade — apt update errors on the Docker repo; you cannot pull engine updates or install Compose plugin cleanly.

Fix 1 — Cannot connect to the Docker daemon (socket and service)

Root cause is usually a stopped docker unit, a failed start after reboot, or a user not in the docker group (so the socket is root-only).

Step 1 — Check engine status and recent logs

sudo systemctl status docker --no-pager
sudo journalctl -u docker -n 80 --no-pager

If the unit is inactive or failed, start and enable it:

sudo systemctl enable --now docker
sudo systemctl restart docker
sudo docker info

Step 2 — Confirm socket and group access

ls -l /var/run/docker.sock
groups
getent group docker

Add your deploy user (replace deploy) and re-login so the group applies:

sudo usermod -aG docker deploy
# log out of SSH fully, then log back in
docker ps

Step 3 — Verify Compose talks to the same engine

docker compose version
docker compose ps

If docker works with sudo but not without, the group/session issue remains—do not paper over it by always using root for day-to-day Compose.

When to call Fixwebnode: the unit crash-loops, docker info errors on storage drivers, or the socket disappears after every reboot. That usually needs unit drop-ins, storage-driver review, or a clean engine reinstall path done carefully on a live host.

Fix 2 — “Port is already allocated” on compose up

Something on the host—or another Compose project—already owns the published port. On Debian app servers this is often leftover nginx/apache, an old container still running, or a second stack in another directory.

Step 1 — See what holds the port (example: 8080)

sudo ss -tlnp | grep ':8080'
sudo lsof -iTCP:8080 -sTCP:LISTEN

Step 2 — List containers and Compose projects using host ports

docker ps --format 'table {{.Names}}\t{{.Ports}}\t{{.Status}}'
docker compose ls

Step 3 — Resolve cleanly

1. If an old container owns the port, stop that stack from its project directory: docker compose down (only if you intend to replace it).
2. If host nginx/apache is bound to 80/443 and your Compose file also publishes those ports, either change Compose to high ports (e.g. 8080:80) and proxy from the host, or stop the host vhost that conflicts.
3. Edit ports: in compose.yaml so host ports are unique, then:

docker compose up -d --remove-orphans
docker compose ps

Step 4 — Confirm the listener

sudo ss -tlnp | grep -E ':(80|443|8080)\s'
curl -I --max-time 5 http://127.0.0.1:8080/ || true

When to call Fixwebnode: multiple reverse proxies, unknown systemd socket units, or production TLS termination you cannot safely reshuffle without a cutover plan. Remote specialists map the full listener chain before changing publish ports.

Fix 3 — Containers exit immediately or never pass healthchecks

Compose “starts” the project, but the app container dies, restarts in a loop, or stays unhealthy. Causes differ from port binds: bad env files, missing secrets, wrong working directory, DB not ready, or a command that exits.

Step 1 — Read service logs and exit codes

docker compose ps -a
docker compose logs --tail=200 web
docker inspect --format='{{.State.Status}} {{.State.ExitCode}} {{.State.Error}}' $(docker compose ps -q web)

Replace web with your service name from the compose file.

Step 2 — Validate env and mount paths on the Debian host

docker compose config
ls -la .env
# confirm bind-mount sources exist and are readable
ls -la ./data ./config 2>/dev/null || true

Fix missing .env keys, incorrect file modes on secrets, or host paths that do not exist (Compose will mount empty dirs and apps then crash).

Step 3 — Dependency order and health

If the app needs the database, use Compose healthchecks and depends_on with condition (Compose v2), then recreate:

docker compose up -d --force-recreate
docker compose ps

Step 4 — Exec in only when the container stays up

docker compose exec web sh -c 'id; pwd; ls -la; printenv | sort | head'

Use this to confirm runtime user, config paths, and env—not as a substitute for fixing the image command.

When to call Fixwebnode: volume data may be corrupt, migrations fail halfway, or you need a zero-downtime recreate across DB and app services. That is past safe solo trial-and-error on a live Fremantle client host.

Fix 4 — No space left: images, cache, and volumes

Debian roots fill quietly with dangling images, build cache, and anonymous volumes. Symptoms: pull/build fails, containers cannot write, or journal and Docker both fight for disk.

Step 1 — Measure before deleting

df -h /
docker system df
docker system df -v | head -n 80

Step 2 — Safe reclaim (unused only)

docker container prune -f
docker image prune -f
docker builder prune -f
docker volume prune -f
docker system df

Step 3 — Deeper clean only when you accept data loss on unused volumes

# destructive for anything not referenced by a container
docker system prune -a --volumes -f
df -h /

Never run destructive prune on production until you know which volumes hold Postgres/MySQL data. Name volumes in Compose and back them up first.

Step 4 — Find large bind mounts outside Docker’s graph

sudo du -xhd1 /var/lib/docker 2>/dev/null | sort -h
sudo du -xhd1 /var/log | sort -h

When to call Fixwebnode: production databases on unnamed volumes, Docker data-root on a full partition with no second disk, or you need a migration of /var/lib/docker to larger storage without losing stacks.

Fix 5 — Docker APT repository or GPG breaks after Debian changes

After a release upgrade or a partial install, apt update fails on download.docker.com, or the engine packages lag behind the Compose plugin. You cannot patch CVEs or install docker-compose-plugin cleanly.

Step 1 — Capture the APT error

sudo apt-get update 2>&1 | tail -n 40
ls /etc/apt/sources.list.d/
. /etc/os-release; echo "$VERSION_CODENAME"

Step 2 — Re-install Docker’s official key and repo (Bookworm example)

sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Step 3 — Install or repair engine + Compose plugin

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker compose version
docker run --rm hello-world

Remove obsolete docker.io-only mixes if you intentionally standardise on Docker CE—avoid running two conflicting install methods on one host.

When to call Fixwebnode: mixed package sources, held broken packages, or live containers you cannot restart while repairing containerd. Remote recovery sequences matter more than re-running install commands blindly.

When DIY is enough vs when to book Fixwebnode

DIY is enough when you have SSH, a non-production window, clear logs, and the fix is local: start the unit, fix group membership, change a published port, correct .env, or prune unused objects after you confirm volumes are disposable.

Book a direct specialist when any of these apply:

• Production data is on the line (databases, uploaded media, irreplaceable volumes).
• The Docker unit crash-loops or the host is out of disk with no safe prune plan.
• You need a repeatable Compose layout (networks, secrets, reverse proxy, TLS) across staging and production.
• Debian upgrade left packaging half-broken and app containers must stay up.

Fixwebnode works as a direct remote provider for this stack—not a freelance board. Geography-wise, support is organised for customers across our service areas, with remote diagnostics suited to Debian hosts developers in Fremantle and elsewhere in WA already operate over SSH.

Talk through your Debian Docker deploy

If Compose will not stay healthy, the daemon will not stay up, or you want a clean deploy path before the next release, start a conversation with the team that works this stack day to day. Bring your Debian version, docker compose ps output, and the exact error line—those three items shorten remote triage dramatically.

Book or enquire via the landing page for Docker & Docker-Compose on Debian and outline the failure mode you are seeing. We will help you stabilise the engine, tighten the Compose project, and get app deployment boring again—in the best way.