Dockge silently broke on Sunday. Diagnosing it took longer than fixing it.

Sunday morning. I check my homelab dashboard out of habit, and Dockge is down. Not crashed, not erroring out in logs — just gone. The container exists. Docker says it’s running. But the web UI won’t load on port 5001.

This is the kind of failure that makes you want to kick the server rack. Not loud enough to scream about. Quiet enough to make you doubt your own setup.

The obvious culprit

First thing: check if the container is actually alive.

docker ps | grep dockge

It’s there. Running. No restart loops, no exit codes. I try hitting localhost:5001 directly. Connection refused. So either the port mapping is broken or something is binding to 5001 that shouldn’t be.

sudo netstat -tlnp | grep 5001

Nothing. Port’s free. So the container isn’t actually listening. That’s weird.

I check docker logs. This is where it gets frustrating:

docker logs dockge

Clean output. No errors. Just the startup messages from when the container launched. Nothing that says “I’m dying here” or “permission denied” or any of the usual suspects.

Chasing permissions like an idiot

My docker-compose.yml for Dockge looks like this:

services:
  dockge:
    image: louislam/dockge:1.4.1
    restart: unless-stopped
    ports:
      - "5001:5001"
    volumes:
      - ./stacks:/opt/stacks
      - /var/run/docker.sock:/var/run/docker.sock
      - dockge-data:/opt/dockge/data
    environment:
      - DOCKGE_STACKS_DIR=/opt/stacks
    user: "0:0"

volumes:
  dockge-data:

The docker.sock volume is the usual suspect for permission headaches. I’ve had Dockge lose the ability to talk to Docker before. So I assumed that’s what happened. Checked socket permissions. They were fine. Restarted the Docker daemon. Nothing.

I even rebuilt the whole compose file from scratch. Still broken. By this point I’m an hour in and starting to get that hollow feeling where you wonder if you broke something fundamental on the host.

The actual problem was stupidly small

I finally exec’d into the container to poke around manually:

docker exec -it dockge /bin/sh

And tried to start the app by hand to see what it actually says:

cd /opt/dockge && node index.js

Port 5001 already in use.

That’s impossible. I just checked. The port is free on the host. And inside the container? There’s nothing running on 5001 yet.

Then it hit me. I checked the dockge-data volume. It’s been mounted on my host for a while. I’ve created stacks, destroyed them, moved things around. What if something in that volume was corrupted?

I backed it up and cleared it:

docker volume rm dockge-data
docker compose up -d dockge

Container started. Port 5001 lit up. Web UI loaded immediately.

The problem wasn’t permissions or the socket mount or the compose file. It was a corrupted database file in the persistent volume that was preventing Dockge from initializing properly. The container was starting, trying to load that broken state, failing silently on some non-critical check, and then just sitting there listening to nothing.

What this taught me

The frustrating part isn’t that volumes can get corrupted. It’s that Dockge’s startup — or at least version 1.4.1 — doesn’t log the specific failure. It just quits trying without telling you why. No “corrupt database” message. No “cannot read file.” Just silence.

In hindsight, I should have checked if the application itself was even starting before I spent time on network and permission debugging. A quick exec into the container and a manual run would have saved 90 minutes. But that’s easy to say when you’re not tired on a Sunday morning.

Dockge works well most of the time. But when it breaks quietly like this, it earns you nothing but frustration. I’ve added a healthcheck to my compose file now, which at least forces Docker to restart the container if it detects the issue sooner:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:5001/api/ping"]
  interval: 30s
  timeout: 5s
  retries: 3

Next time it breaks, Docker will catch it before I have to manually check. Still wish the app itself would just tell me what’s wrong.

Explore Dockge in our AI Homelab Toolkit.