DockerSelf-Hosting

Dockge with Docker: a simple web UI for Compose stacks (Linux, Windows, Mac)

Before you start

  • 20 min read

Boxes marked Run in terminal are what you type; plain text explains why. Check what you need first

What you get in one minute#

Dockge is a free, self-hosted web page for your compose.yaml files: you create, edit, start, stop and update Docker Compose stacks in the browser, while the files stay on your disk and still work with plain docker compose.

Dockge official logo

Logo: the official Dockge project (github.com/louislam/dockge)

It suits a home lab where you already write Compose files and want a nicer editor, live pull and deploy progress, and a list of stacks with their state. One honest note first: the latest release, 1.5.0, is from March 2025. The repository still gets commits (the newest I could see is dated October 2026), but the project moves slowly. Treat it as a stable tool, not one that changes weekly.

WhatValue (official sources, read November 2026)
Current versionDockge 1.5.0, released 30 March 2025 (latest stable). Before it: 1.4.2, January 2024
Image to pinlouislam/dockge:1.5.0 (tag exists on Docker Hub for amd64, arm64 and armv7)
Time neededAbout 15 minutes (our estimate, not measured)
Size and RAMThe project publishes no figures; measure with docker stats
PortTCP 5001 (the web UI)
LicenceMIT (LICENSE at the release tag). No paid edition is mentioned
Official docsREADME at 1.5.0 and the Compose generator

Screenshot of the Dockge main screen: a list of stacks on the left, the nginx stack with Edit, Restart, Update, Stop and Delete buttons, its container, a live terminal and the compose.yaml editor

Image: the official Dockge project (README at 1.5.0). It is an older screenshot from 2023; labels and the Console tab (off by default now) may differ.

At a glance:

  • What it is: one Docker container with a web UI. It edits compose.yaml files in a folder you choose and runs docker compose for you.
  • Files stay yours: no hidden database of stacks. Stop Dockge and the stacks and files still work.
  • Needs the Docker socket: that is powerful. A hacked Dockge is a hacked Docker host. The author warns against putting it on the internet.
  • Linux server only: the README lists Linux and marks Windows unsupported. Windows and Mac are browsers and SSH clients here.
  • Narrow on purpose: Compose stacks only. For single containers and Docker networks you need another tool.
  • Pin the tag: the official file uses louislam/dockge:1; we pin 1.5.0.

How it fits together#

Two-lane diagram: you in a browser reach the Dockge container on port 5001, optionally through an SSH tunnel or Caddy; on the Docker host, Dockge reads and writes compose.yaml files in the stacks folder and sends compose commands through the Docker socket, which creates your app containers

Drawn for this guide from the official compose file and README. The access path (dashed) is optional but recommended.

Dockge keeps its login and settings in a small SQLite database (dockge.db) in its data folder. Your stacks are not in it.

Before you start#

Linux server: Ubuntu, Debian (Bullseye or newer), Raspbian (Bullseye or newer), CentOS, Fedora or Arch, with Docker 20 or newer (or Podman with podman-docker). Architectures: amd64, arm64, armv7. The README gives no RAM or disk figures.

Run in terminalbash
docker --version
docker compose version
uname -m

Windows: not a server ("Windows (Will be supported later)", says the README). You need PowerShell for SSH and a browser:

Run in terminalpowershell
ssh -V

Mac: not a server either; the README does not list macOS. Terminal and a browser are enough:

Run in terminalbash
ssh -V

Checklist:

  • [ ] Docker and the Compose plugin on the Linux server
  • [ ] Port 5001 free on the server (ss -ltn | grep 5001 shows nothing)
  • [ ] A folder for the stacks. We use /opt/stacks, the official default
  • [ ] For the HTTPS section only: a domain name with a DNS record and ports 80 and 443 free

Tested by DIY Lab Hub: not yet. The commands come from the official README, compose file and source at the 1.5.0 tag. We did not run them.

Step 1: Create the folders on the Linux server#

Dockge needs a folder for itself and a stacks folder for your compose files. The stacks path must be a full path and identical inside the container and on the host; the official compose file warns about it in capitals.

Linux#

Run in terminalbash
mkdir -p ~/docker_volumes/dockge/{data,backups}
sudo mkdir -p /opt/stacks
cd ~/docker_volumes/dockge

We use /opt/stacks, the official default. Dockge runs as root, so files it creates there belong to root; use sudo to read them in a shell.

Windows (PowerShell)#

Not supported as the server. Open an SSH session to your Linux server and run the Linux commands there:

Run in terminalpowershell
ssh <your-user>@<your-server-address>

Mac (Terminal)#

Not supported as the server. Same SSH command, then the Linux commands:

Run in terminalbash
ssh <your-user>@<your-server-address>

Check it worked. Both folders exist:

Run in terminalbash
ls -ld ~/docker_volumes/dockge/data /opt/stacks

Tip: Decide the stacks path now. Changing it later means editing three places and moving folders by hand.

Step 2: Write the Compose file and start Dockge#

This is the official file with three changes: the tag is 1.5.0, the UI is published on 127.0.0.1 only (the official file publishes it on every interface), and we add container_name. The README downloads the file from master; we write it out so nothing moves under you.

Linux#

Run in terminalbash
cd ~/docker_volumes/dockge
cat > docker-compose.yml << 'EOF'
services:
  dockge:
    image: louislam/dockge:1.5.0
    container_name: dockge
    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
EOF
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=50 dockge

Windows (PowerShell)#

Not supported as the server. Run the same file on the Linux server over SSH (Step 1).

Mac (Terminal)#

Not supported as the server. Run the same file on the Linux server over SSH.

Check it worked. docker compose ps shows dockge running. The image has a health check (every 60 seconds, 60-second start period, from the Dockerfile), so it turns healthy after about a minute. The source logs Listening on 5001, and on a fresh install No user, need setup, which is normal. The README promises "Dockge is now running on http://localhost:5001". We show no real output because we did not run it.

Tip: This docker-compose.yml is Dockge's own file and stays in ~/docker_volumes/dockge. Dockge only lists stacks inside the stacks folder, so it does not show itself. That is fine.

Step 3: Reach the page and create your admin account#

The UI listens only on the server's loopback address. An SSH tunnel carries your local port 5001 to it.

Linux#

On the server itself, open http://127.0.0.1:5001. From another Linux computer, open the tunnel and leave it running:

Run in terminalbash
ssh -N -L 5001:127.0.0.1:5001 <your-user>@<your-server-address>

Then open http://localhost:5001.

Windows (PowerShell)#

Run the same command and keep the window open:

Run in terminalpowershell
ssh -N -L 5001:127.0.0.1:5001 <your-user>@<your-server-address>

Then open http://localhost:5001 in your browser. If ssh is missing, add the OpenSSH client in Windows optional features.

Mac (Terminal)#

Same as Linux:

Run in terminalbash
ssh -N -L 5001:127.0.0.1:5001 <your-user>@<your-server-address>

Then open http://localhost:5001.

The first page is a setup page: choose a username and a password. There is no default login. Weak passwords are rejected with Password is too weak. It should contain alphabetic and numeric characters. It must be at least 6 characters in length. That is the lowest bar; choose a long one.

Check it worked. You are logged in and see the stack list with a + Compose button. If you had existing stacks, they are not listed yet (Step 5).

Tip: Save the password in a password manager before you close the page. The setup screen runs once: Dockge has been initialized. If you want to run setup again, please delete the database. Deleting the database also deletes your settings, so do not do it lightly.

Step 4: Deploy a first test stack#

A small stack proves the whole chain.

Linux#

In Dockge click + Compose. Type the stack name whoami (lowercase only; the field says "Lowercase only"). Replace the YAML with this and press Deploy:

File contentyaml
services:
  whoami:
    image: traefik/whoami:v1.11.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:80"

Then, on the server:

Run in terminalbash
curl -s http://127.0.0.1:8081
sudo ls /opt/stacks/whoami

Windows (PowerShell)#

Do the clicking in your browser through the tunnel. For the check, ask the server over SSH:

Run in terminalpowershell
ssh <your-user>@<your-server-address> "curl -s http://127.0.0.1:8081"

Mac (Terminal)#

Same in the browser, then:

Run in terminalbash
ssh <your-user>@<your-server-address> "curl -s http://127.0.0.1:8081"

Check it worked. The curl prints a few lines including Hostname: (the traefik/whoami test image does that), /opt/stacks/whoami holds a compose.yaml, and Dockge shows the stack as active. Stop and Delete it when done.

Tip: Dockge writes compose.yaml into /opt/stacks/<name>/. If a stack lives anywhere else, Dockge cannot manage it.

Step 5: Bring your existing stacks in#

Dockge only manages stacks inside its stacks folder. The README's steps for an existing stack:

Linux#

  1. Stop the stack with docker compose down.
  2. Move its compose file (and .env, data folders) to /opt/stacks/<stackName>/compose.yaml.
  3. In Dockge open the top-right dropdown and click Scan Stacks Folder, then start the stack.
Run in terminalbash
cd ~/my-old-stack
docker compose down
sudo mkdir -p /opt/stacks/my-old-stack
sudo mv compose.yaml .env data /opt/stacks/my-old-stack/

Dockge also accepts docker-compose.yaml, docker-compose.yml and compose.yml (checked in the source). Keep the folder and project names lowercase and equal, or the stack may show as unmanaged.

Windows (PowerShell)#

Do the moves on the Linux server over SSH, then click Scan Stacks Folder in the browser.

Mac (Terminal)#

Same: move files on the server, scan in the browser.

Check it worked. The stack is in the list and its containers run after you start it. Check your data is still there before you delete anything old.

Put it behind HTTPS (with or without Traefik)#

The author's own advice is to keep Dockge off the internet and reach it through Tailscale or WireGuard (see our wg-easy and Headscale guides). HTTPS is still worth having on a private network, so your password is not sent in clear text. If you use the SSH tunnel, skip this section. Both routes need a DNS record for a name such as dockge.<your-domain>.

With Traefik#

On a server that already runs Traefik v3 with the Docker provider, add labels and remove the host port.

This assumes an external network proxy and an entrypoint https (use your own names). Create the network once:

Run in terminalbash
docker network create proxy

Replace ~/docker_volumes/dockge/docker-compose.yml:

File contentyaml
services:
  dockge:
    image: louislam/dockge:1.5.0
    container_name: dockge
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
      - /opt/stacks:/opt/stacks
    environment:
      - DOCKGE_STACKS_DIR=/opt/stacks
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.dockge.rule=Host(`dockge.<your-domain>`)"
      - "traefik.http.routers.dockge.entrypoints=https"
      - "traefik.http.routers.dockge.tls=true"
      - "traefik.http.services.dockge.loadbalancer.server.port=5001"

networks:
  proxy:
    external: true

Start it with docker compose up -d in that folder. Dockge uses WebSockets (Socket.IO); Traefik passes them through. Do not rewrite the Host header (see "Troubleshooting").

Check it worked. curl -I https://dockge.<your-domain>/ returns an HTTP status line over HTTPS and the login page opens with a valid certificate.

Without Traefik: Caddy#

Choose this if you have no Traefik. Caddy gets and renews its own certificates.

Caddy's docs describe automatic Let's Encrypt certificates for a public domain, tls internal for a local certificate at home, and WebSocket support in reverse_proxy. Create the Caddy folder:

Run in terminalbash
mkdir -p ~/docker_volumes/caddy/{conf,data,config}
cd ~/docker_volumes/caddy

Save this as ~/docker_volumes/caddy/docker-compose.yml. The image is caddy:2.11.9, the latest Caddy release read in November 2026:

File contentyaml
services:
  caddy:
    image: caddy:2.11.9
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy:ro
      - ./data:/data
      - ./config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true

Save this as ~/docker_volumes/caddy/conf/Caddyfile for a public domain:

File contenttext
dockge.example.com {
    reverse_proxy dockge:5001
}

For a home-only name use tls internal:

File contenttext
dockge.home.arpa {
    tls internal
    reverse_proxy dockge:5001
}

Caddy reaches Dockge by its container name on the shared proxy network. In Dockge's docker-compose.yml remove the ports: block, add the proxy network exactly as in the Traefik file, and leave out the labels. Then start both:

Run in terminalbash
docker network create proxy
cd ~/docker_volumes/caddy && docker compose up -d
cd ~/docker_volumes/dockge && docker compose up -d

(If proxy exists, the first command only prints an error.) For a home-only certificate, Caddy's docs say that in a container you install the root certificate on each device yourself:

Run in terminalbash
docker exec caddy find /data -name root.crt
docker cp caddy:<path-from-find> ./caddy-root.crt

Install caddy-root.crt as a trusted root on each device (our advice, not from the docs): Windows, "Trusted Root Certification Authorities"; macOS, Keychain Access with "Always Trust"; Linux, your CA store. Run the docker commands on the Linux server only.

Check it worked. curl -I https://dockge.example.com/ returns an HTTP status line over HTTPS. For a home-only name, the padlock appears only after the root certificate is trusted on that device.

Tip: Dockge compares the browser's Origin with the Host header and refuses the socket if they differ. Caddy and Traefik keep the original Host; do not rewrite it.

Security and testing#

Anyone who gets into Dockge can start any container on the host and mount any folder. Plan for that.

ControlHow
Not on the internetKeep 127.0.0.1:5001 plus a tunnel, or a VPN. The author says so in the project discussions. Never forward port 5001 on the router
Admin passwordLong and unique. There is no default account; the setup page creates it. Change it in Settings, Security
Do not turn off authenticationSettings, Security has "Disable Auth". The UI says it is for when you put another login (Authelia, Cloudflare Access, and so on) in front. Without one, anyone who reaches the page owns the host
Console stays off1.5.0 disabled the Console tab by default "due to the security reason". DOCKGE_ENABLE_CONSOLE=true turns it on; leave it off unless you need a shell in the browser
Socket mount:ro on the socket does not make the Docker API read-only (our advice)
Data folder~/docker_volumes/dockge/data holds the database with the login. chmod 700 ~/docker_volumes/dockge (our advice)
Stack .env filesOften hold passwords. Treat /opt/stacks as secret
Update checkThe server asks https://dockge.kuma.pet/version every 48 hours. Untick "Show update if available" under Settings, About to stop it

Quick tests on Linux after each change:

Run in terminalbash
cd ~/docker_volumes/dockge
docker compose ps
docker compose logs --tail=100 dockge
curl -I http://127.0.0.1:5001/

There is no /health page; the image's health check requests /. Windows (curl.exe) and Mac can run the same curl -I https://dockge.<your-domain>/.

Dockge, Portainer, Komodo or plain Compose?#

ToolGood atWatch out for
DockgeCompose files as plain files, live pull and deploy output, small and simple, several hosts through agentsCompose only; slow release pace; powerful socket access
PortainerMany Docker features, including networks and single containers (the Dockge README says so). See our older Portainer guideBigger and more to learn. The README says you can run both
KomodoServers, stacks, builds and automations from one UI. See our Komodo guideHeavier setup with a database and agents
Plain docker composeNo extra service and no extra socket accessNo browser editor

If you only need Compose, Dockge is simpler. For networks or single containers it is not a replacement.

Unofficial fork. Dockge Enhanced (announcement) adds backups and more. It is not the official Dockge and we have not tested it.

Common mistakes#

From the official README, compose file, release notes, and real GitHub issues and discussions.

MistakeWhy it happensDo this instead
Using a different path on each side of the stacks mount, such as /docker:/my-stacksThe compose file warns: "Left Stacks Path === Right Stacks Path (MUST)". Docker acts on host paths, so data can end up in the wrong placeUse the same full path in the mount (both sides) and in DOCKGE_STACKS_DIR
A stack with capital letters or an odd name shows "not managed by dockge"Issue 19: Compose lowercases project names, but Dockge looked for the original name. The reported fix was renaming the folder to lowercase and rescanning. The UI field now says "Lowercase only"Use lowercase names. Rename the folder in /opt/stacks, then Scan Stacks Folder
Treating Error: spawn docker ENOENT as a missing DockerIssues 361 and 424: reporters hit it on Windows 11 and with existing stacks. One fixed it with the right user, group and permissions on the stacks folder and socketRun on Linux, check the stacks folder exists and is writable, test docker exec dockge docker compose version
Stacks vanish after a Docker upgrade but the containers keep runningIssue 899: a commenter explains that Docker 29 raised the minimum API version, so an older Dockge could no longer list stacks. Updating to 1.5.0 fixed it for the reporterRun Dockge 1.5.0 or newer; do not pin 1.4.2. Do not delete anything until you have checked the version
Port-forwarding 5001 or putting it on a public nameIt looks like any other web app. The author says it "can control all your docker containers" and advises Tailscale or WireGuard instead (discussion 336)VPN or SSH tunnel; if you add HTTPS, keep it on your network
Pressing "Disable Auth" to skip the loginThe setting exists for third-party logins in front of Dockge, and says soKeep authentication on. Use a strong password
Enabling the Console because the tab is missing1.5.0 disabled it by default for security. It is not part of the installLeave it off; use SSH for a shell. If you must, set DOCKGE_ENABLE_CONSOLE=true and know the risk
Expecting /dockge as a sub-path behind a proxyDiscussions 468 and 874: the frontend assumes the root path. A base-path pull request (947) exists, but it is not in 1.5.0Use a host name such as dockge.<your-domain>
Random disconnects behind CaddyIssue 711: one reporter fixed it by closing a download-manager browser extension; another saw it when Caddy reloaded its configurationTest in a private window without extensions; compare with direct access
Moving a compose file and thinking the data movedDiscussion 484: a new volume starts empty; named volumes live outside the stack folderKeep data inside each stack folder, like /opt/stacks/app/data, and move the whole folder
Swapping to another fork's image and backA fork author warns that his image changes the database and that stock Dockge may then complain about a missing migration (discussion 844)Back up data/ before you try any fork; restore it to go back
AI assistants: wrong image, port or settingsTypical wrong answers: an image named dockge/dockge (it is louislam/dockge), port 3000 (it is 5001), a version: "3.8" line (1.5.0 dropped the obsolete line), PUID and PGID (only in unreleased code), a BASE_URL setting, a login admin/admin, PostgreSQL or Redis (it uses SQLite)Copy only from the official README and compose file at the tag you pin

Tip: The current master README is ahead of 1.5.0. It shows PUID and PGID, which the 1.5.0 source does not read. Always read the README at the tag you run (/blob/1.5.0/README.md).

Tip: :1 means "any 1.x". Today it is the same image as 1.5.0, but a later 1.x would arrive on the next pull. A fixed tag makes updates your decision.

Troubleshooting#

ProblemSolution
Page does not opendocker compose ps and docker compose logs --tail=100 dockge. Is the tunnel running?
Bind for 127.0.0.1:5001 failed: port is already allocatedAnother program uses 5001. Stop it or change the left side of the port line, for example 127.0.0.1:5002:5001
Error: spawn docker ENOENT in the logSee "Common mistakes". Check the stacks folder exists inside the container: docker exec dockge ls /opt/stacks
Origin (...) does not match host (...)The proxy changed the Host header, or you use another name or port than the proxy serves. Fix the proxy. UPTIME_KUMA_WS_ORIGIN_CHECK=bypass exists but removes a security check; do not use it as a fix
Invalid origin url (...)The Origin header was damaged by a proxy or extension. Test without the proxy
Stack list empty after a Docker or OS upgradeCheck the Dockge version under Settings, About. 1.5.0 fixed the Docker 29 case (issue 899)
Stack shows as "unmanaged"Folder and project name must match, in lowercase. Rename the folder, then Scan Stacks Folder
Console tab missingIntentional in 1.5.0. Set DOCKGE_ENABLE_CONSOLE=true only if you accept the risk
Error: Cannot find 'frontend-dist/index.html', did you install correctly?The built web files are missing. Pull the image again; do not mount a folder over /app
Failed to prepare your database: ...Read the text after the colon. Check data/ is writable and the disk is not full. Keep the folder; do not delete it
Permission denied talking to Docker (on the host)Add your user to the docker group or use sudo

Dockge says the setup was already done#

The message is Dockge has been initialized. If you want to run setup again, please delete the database. It means an account exists. Log in. If you lost the password, the only route in the source is deleting the database file, which also resets Dockge's settings. Stop the container, back up data/, then remove data/dockge.db* and start again. Your stacks are not touched.

Known bugs#

  • Issue 711: disconnects behind a proxy in one browser. No fix confirmed in the thread.
  • Discussion 725: terminal output shows only some log lines behind an older proxy. No fix confirmed; compare with docker compose logs.
  • Slow project: there is no 1.5.x bug-fix release; fixes may reach only the nightly image, which we do not recommend for a server.

Updates and backups#

Update. There is no newer stable release than 1.5.0 today. To follow a future one, read its release notes, change the tag in docker-compose.yml, and run:

Run in terminalbash
cd ~/docker_volumes/dockge
docker compose pull
docker compose up -d
docker compose logs --tail=100 dockge

With a fixed tag the pull does nothing until you change the tag. A stack's Update button in the UI pulls new images for that stack.

Back up. Dockge uses SQLite, which keeps recent writes in extra files next to dockge.db. Copy it while stopped, so the files agree. The stacks folder is root-owned, so use sudo:

Run in terminalbash
cd ~/docker_volumes/dockge
docker compose stop dockge
mkdir -p backups
sudo tar -czf "backups/dockge-$(date +%F).tar.gz" data docker-compose.yml /opt/stacks
sudo chmod 600 backups/dockge-*.tar.gz
docker compose start dockge

This saves Dockge's database, its compose file and every stack's files, but not named Docker volumes or bind mounts outside /opt/stacks. Back those up per app (see our restic backup guide).

For a nightly run at 03:00, add the same commands to crontab -e with 0 3 * * *. Keep a copy on another machine.

Restore test. Unpack into a new empty folder, never over the live one:

Run in terminalbash
mkdir -p /tmp/dockge-restore && sudo tar -xzf backups/dockge-<date>.tar.gz -C /tmp/dockge-restore
sudo ls /tmp/dockge-restore/data

You should see dockge.db. A real restore: stop Dockge, move data to data.old, unpack, start.

Windows (PowerShell)#

Not for the server. Copy the archive off the Linux server from your PC:

Run in terminalpowershell
scp <your-user>@<your-server-address>:~/docker_volumes/dockge/backups/dockge-<date>.tar.gz .

Mac (Terminal)#

Use the same scp command from Terminal.

Performance and resources#

The project publishes no RAM, CPU or disk figures, so this guide gives none. Discussion 620, "Dockge and ram usage", has users asking why memory looks high, with no firm answer.

  • Measure: docker stats dockge shows live CPU and memory.
  • Many stacks: no limit is documented.
  • More hosts: run Dockge on each host and add it as an agent (introduced in 1.4.0), so one UI manages several hosts.

FAQ#

Is Dockge still maintained? Slowly. The last release is from March 2025, the newest commit I saw from October 2026. Some users call it abandoned. It works today, but expect few changes.

Can I run it on Windows or macOS? The README says Windows will be supported later, and does not list macOS. Run it on a Linux server and use Windows or Mac as the browser.

Does it replace Portainer? Only if you use Compose only. For networks or single containers, no. You can install both.

Does Dockge send my data anywhere? The source asks https://dockge.kuma.pet/version for the newest version every 48 hours and sends no stack content. It is the only call we found, not a full privacy audit. Untick "Show update if available" in Settings to stop it.

Does it have SSO or OIDC? Not that we could find. It has a built-in login, and "Disable Auth" for use behind another login (untested by us).

Sources#

Checked against the official docs on 2026-11-16.