Dockge: a compose.yaml stack manager for self-hosted Docker

What Dockge is for, and who it is not for

Dockge manages compose.yaml files. That is the whole scope. The README states the main objective plainly: "The main objective of Dockge is to try to use the docker `compose.yaml` for everything." Everything else in the interface follows from that decision. Create, edit, start, stop, restart and delete a stack, update its images, open a terminal into it, and convert a `docker run ...` command into a compose file.

The intended user is someone who already runs `docker compose up -d` on a Linux box and wants a UI that shows progress and errors in real time. The author's motivation section describes the frustration that produced it: while using Portainer for stack management, "sometimes when I try to deploy a stack, the loading icon keeps spinning for a few minutes without progress. And sometimes error messages are not clear." Dockge is the answer to that specific complaint, not a general Docker control panel.

The README is direct about who should look elsewhere. Asked whether a single container can be managed without a compose file, it answers: "If you want to manage a single container, you can just use Portainer or Docker CLI." If your work is mostly networks, volumes and one-off containers, Dockge covers none of it. That is a deliberate boundary, not a missing feature.

The file-based design and what it changes in practice

The architectural decision that separates Dockge from most Docker dashboards is that stacks live on your filesystem. The README says Dockge "won't kidnap your compose files, they are stored on your drive as usual. You can interact with them using normal `docker compose` commands." There is no import step and no internal database of stack definitions. The default stacks directory is `/opt/stacks`, and each stack is a directory containing a `compose.yaml`.

The container needs the Docker socket at `/var/run/docker.sock` and a data volume at `./data:/app/data`. The stacks directory is mounted host-path to identical container-path, and the README warns twice in the compose file that this must be a full path with no relative path, and that the left and right sides must match. Violating that rule is called out as a data-loss risk: "If you did it wrong, your data could end up writing into a WRONG PATH." That is an unusual failure mode. A misconfigured volume here does not produce an error screen, it produces files in the wrong place.

Because the files stay on disk, the UI is not the only way in. You can edit a compose file with an editor, run `docker compose up -d` from the stack directory, and Dockge's view of the stack reflects the same file. The trade-off is that Dockge has no concept of a stack it has not seen: existing stacks have to be moved into the stacks directory and picked up with the Scan Stacks Folder button before they appear.

Version 1.4.0 added multiple agents, which the README describes as managing "multiple stacks from different Docker hosts in one single interface." That is the mechanism for reaching beyond the single host where Dockge runs.

Installing Dockge on Ubuntu or Debian and starting the first stack

The README lists Docker 20+ or Podman as the requirement, with major Linux distributions such as Ubuntu, Debian Bullseye or newer, Raspbian Bullseye or newer, CentOS, Fedora and ArchLinux supported. Debian or Raspbian Buster and lower are explicitly unsupported, as is Windows. Architectures are armv7, arm64 and amd64.

The basic install creates two directories, downloads the compose file and starts the container:

mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge
curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml
docker compose up -d

The README notes that if you are on docker-compose V1 or Podman you should use `docker-compose up -d` instead. After that, the README says Dockge is running on http://localhost:5001. The default port is 5001 and the default stacks directory is `/opt/stacks`.

If you want a different port or stacks path, the README points at a generator URL rather than hand-editing the file:

curl "https://dockge.kuma.pet/compose.yaml?port=5001&stacksPath=/opt/stacks" --output compose.yaml

With the file in place, the container definition itself is small. This is the shape the README gives, and the two path warnings are the part worth reading twice:

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

To bring an existing stack under management, the README gives four steps: stop the stack, move the compose file to `/opt/stacks/<stackName>/compose.yaml`, click Scan Stacks Folder in the top-right dropdown menu, and the stack appears in the list. The first real use is usually that migration rather than creating a stack from scratch.

If you want stack files owned by a specific user rather than root, the README says to add both variables to the environment section, and notes that "Both PUID and PGID must be set for it to do anything":

      - PUID=1000
      - PGID=1000

Updating Dockge itself is two commands from the install directory:

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

For private registries, the compose file carries a commented line for sharing `/root/.docker/` with the container.

Limits, failure modes and the Windows gap

The clearest limitation is scope. No networks, no volumes, no single containers without a compose file. If your environment is a handful of standalone `docker run` invocations, Dockge will feel like an empty room.

The second is the path requirement. Dockge needs the host stacks path and the container stacks path to be identical, and the README treats a mistake here as a data-integrity problem rather than a startup error. Anyone who mounts `/opt/stacks` on the host to something like `/stacks` inside the container is outside the documented configuration.

Windows is listed as unsupported, with the README saying it "Will be supported later." There is no date attached to that statement, and the last push to the repository was on 2025-03-30, so treat Windows support as unshipped rather than imminent. Debian Buster and older are also out.

Podman works, but only with the `podman-docker` compatibility package, which the README gives as `apt install podman-docker` on Debian. That is an extra dependency in the path, and the README does not describe what differs once you are running under Podman.

Finally, the project's own release history is thin. Version 1.5.0 landed on 2025-03-30, and the previous release, 1.4.2, was on 2024-01-21, roughly fourteen months earlier. Nothing in the repository is archived, but a reader deciding today should weigh a release cadence measured in quarters against how much they depend on the UI.

Dockge against Portainer and the narrower alternatives

The comparison the README addresses head-on is Portainer. Its answer to "Is Dockge a Portainer replacement?" is "Yes or no." Portainer covers a wide set of Docker features; Dockge covers compose files with what the author considers a better interface. The README's own rule: if you manage containers with docker-compose only, the answer may be yes; if you also need networks and single containers, the answer is no. Both can run side by side, and the README confirms installing both is fine.

Portainer's stack deployment goes through its own store and can take minutes with unclear errors, according to the motivation section. Dockge's counter-approach is to keep the file on disk and stream the pull and up output in real time, so the compose file you see in the editor is the one on the filesystem. That difference matters most when something fails: with Dockge you can drop into the interactive web terminal and run `docker compose` yourself against the same directory.

For people who want a full Docker management platform rather than a compose editor, Portainer remains the broader tool. For people who want a lighter interface over the same files, Dockge is the narrower one. The choice is about whether you want the UI to own your stack definitions or merely to edit them.

Maintenance, licence and what upgrading costs

Dockge is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive licence with no copyleft obligation on your own code, but it is not legal advice and the LICENSE file in the repository is the authoritative text.

Upgrade cost is low by design. The documented update path is `docker compose pull && docker compose up -d` from `/opt/dockge`. Because stacks are files on disk and there is no internal database of stack definitions, a Dockge upgrade does not migrate or rewrite your compose files. The data volume at `./data:/app/data` is the only state to preserve.

The maintenance picture is the part to watch. The repository is not archived, and the last push was on 2025-03-30, which is well beyond six months before today. Version 1.5.0 shipped on that same date, after a gap of about fourteen months from 1.4.2. That is a project with a slow release rhythm, and anyone building a workflow around the multiple-agents feature added in 1.4.0 should confirm it behaves as documented on their own hosts rather than assuming fixes will arrive quickly.

Editorial conclusion

Adopt Dockge if you already think in compose.yaml files and want a web UI that edits those files in place instead of importing them into a database; skip it if you need to manage bare containers, Docker networks or volumes, which the README explicitly leaves to Portainer or the Docker CLI. Before committing, verify two things on your own host: that the stacks path is identical on the left and right side of the volume mount, and that the compose file you want to manage has been moved into /opt/stacks/<stackName>/compose.yaml and picked up by Scan Stacks Folder. Also check the last push date, 2025-03-30, against your tolerance for a project that is not currently shipping releases.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes