Learning Center

Run Dockge for Managing Docker Compose Stacks

Add a simple web UI for Docker Compose stacks without abandoning file-based workflows, then keep the sensitive stack directory and Docker socket under tighter control than the average dashboard tutorial bothers to mention.

Dockge Docker Compose Stack management

Illustrated guide cover for Run Dockge for Managing Docker Compose Stacks — Dockge • Docker Compose • Stack management

What you learn

How to deploy Dockge, map a real stacks directory correctly, import existing Compose projects, and keep the UI private by default.

Best for

Operators who already manage apps with compose.yaml files and want a lighter interface than a full Docker platform.

Risk to watch

If the host and container stack paths do not match exactly, Dockge can write stack data into the wrong place and create a confusing mess.

Before you begin

A Linux host with Docker Engine 20+ and the Compose v2 plugin working.
Comfort editing Compose files directly on disk.
A plan for private access, such as Tailscale, a local-only bind, or a reverse proxy with authentication.
A clear directory where your Compose stacks should live, such as /opt/stacks.

Dockge's official install docs still center on a default stacks directory of /opt/stacks, a default web port of 5001, and a warning that the stacks path on the host and inside the container must match exactly. That last point is not a style preference. It is an integrity rule.

Expected outcome: you will finish with Dockge running as its own Compose stack, aware of a dedicated stacks directory, while your actual app definitions remain plain files you can still manage with docker compose.

Step 1: Prepare a real stacks directory

Create both the Dockge app directory and the shared stacks directory:

sudo mkdir -p /opt/dockge /opt/stacks
sudo chown -R $USER:$USER /opt/dockge /opt/stacks
cd /opt/dockge

Keep your Compose projects under one predictable root. The simplest model is one directory per stack, each containing a compose.yaml file:

/opt/stacks/
  traefik/
    compose.yaml
  uptime-kuma/
    compose.yaml
  vaultwarden/
    compose.yaml

Warning: do not map /opt/stacks on the host to a different path inside the container. Dockge's upstream docs explicitly warn against that mismatch because it causes writes to land in the wrong place.

Step 2: Deploy Dockge with Compose

Save this as /opt/dockge/compose.yaml:

services:
  dockge:
    image: louislam/dockge:1
    restart: unless-stopped
    ports:
      - 127.0.0.1:5001:5001
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /opt/stacks:/opt/stacks
    environment:
      - DOCKGE_STACKS_DIR=/opt/stacks

Binding the web port to 127.0.0.1 keeps Dockge off the public internet until you deliberately place it behind a private tunnel or an authenticated reverse proxy.

docker compose up -d
docker compose ps

Then confirm the container is healthy before continuing:

docker logs dockge --tail 100

Step 3: Import or create stacks safely

Dockge is designed around Compose files. If you already have running projects outside the stacks directory, stop them cleanly first, move their compose file into /opt/stacks/<stack-name>/compose.yaml, and then rescan the folder in Dockge.

For a new stack, create a directory and keep the definition simple:

mkdir -p /opt/stacks/hello-nginx
cat > /opt/stacks/hello-nginx/compose.yaml <<'YAML'
services:
  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - 8088:80
YAML

cd /opt/stacks/hello-nginx
docker compose up -d

Once the file exists in the stacks directory, Dockge should see it after a scan even if you still use the CLI for day-two work. That is the right mindset: Dockge as a manager for Compose files, not as a magical replacement for understanding them.

Step 4: Keep the UI private by default

Dockge has Docker socket access and direct visibility into stack definitions. Treat it like an admin tool, not a casual public web app. Good access patterns include:

SSH port forwarding to 127.0.0.1:5001
A private network like Tailscale or WireGuard
An authenticated reverse proxy such as Authelia, Authentik, or Cloudflare Access

If you already run a reverse proxy, point it at Dockge's local bind instead of reopening the container directly on all interfaces.

Step 5: Operate and update Dockge

Useful routine checks:

docker compose ps
docker logs dockge --tail 50
find /opt/stacks -maxdepth 2 -name 'compose.yaml'

To update Dockge itself:

cd /opt/dockge
docker compose pull
docker compose up -d

Update one stack at a time when possible. If a stack definition changes unexpectedly after editing in the UI, compare it against version control or your last known-good copy before restarting production services.

Rollback and recovery notes

Dockge's real value is that your stacks stay as plain files. If the UI breaks, your Compose projects are still recoverable with ordinary CLI commands:

cd /opt/stacks/vaultwarden
docker compose ps
docker compose up -d

Back up both /opt/stacks and /opt/dockge/data. The first is operationally critical. The second stores Dockge's own metadata and preferences.

Troubleshooting

Dockge starts but shows no stacks.
Confirm your Compose files live under /opt/stacks/<name>/compose.yaml and rescan the stacks folder from the UI.

Changes appear in a weird path.
Check the host/container path mapping. The left and right side of the stacks volume must match.

The UI is reachable publicly.
Move the port bind to 127.0.0.1:5001:5001 or put an authenticated reverse proxy in front of it immediately.

A stack update fails from the UI.
Open the stack directory directly and run docker compose config or docker compose up -d from the CLI to see the raw error.

What to do next: continue with How to Deploy Docker Compose Apps on a VPS, Set Up Traefik as a Docker Reverse Proxy With Automatic HTTPS, and How to Set Up Restic Backups for Docker Volumes.