Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Nov 2026
verified on Ubuntu 26.04 · Nov 2026Self-host Dockge, the compose stack manager, on a small VPS — pinned image, a loopback port behind Caddy HTTPS with working websockets, and the Docker socket risk stated plainly.
Dockge is a web manager for Docker Compose stacks, from
the author of Uptime Kuma. You create, edit, start,
stop, restart and delete compose.yaml stacks in an interactive editor,
watch pull, up and down progress live, and open a web terminal into a
container. The upstream README stresses that it is file based: "Dockge won't
kidnap your compose files, they are stored on your drive as usual", so you can
keep using plain docker compose on the same stacks. It is MIT
licensed, a TypeScript, Vue and Node.js application, and rated 1 / 5 to
deploy: one container, one SQLite file, no database server.
Maintenance and known advisory. The latest release is 1.5.0 (30 March 2025),
the version pinned here, and no newer one exists. GitHub advisory
GHSA-r5ph-2fqc-qvf3 (rated high, published August 2026) describes a stack-name
path traversal: the name check in Stack.validate() is reached only when a
stack is saved, while Stack.getStack joins the name onto the stacks
directory unchecked, so a name containing ../ can read the .env and compose
files of other directories or delete a directory. We read the 1.5.0 source and
it matches: validate() is called only from save(). The advisory lists no
fixed or affected version range, and there is no fixed release. It needs a
logged-in user, and a logged-in Dockge user can already take over the host
through the Docker socket, so it adds little beyond what the login already
grants, but it becomes unauthenticated if you enable the disableAuth
setting. Never enable disableAuth. (A separate console-injection
advisory, GHSA-7vx4-hf96-mqq6, affects 1.4.2 and earlier and is fixed in 1.5.0.)
Read the next paragraph before you install. Dockge works by mounting
/var/run/docker.sock into its container. Access to the Docker socket is
root-equivalent on the host: anyone who can drive Dockge can start a
container that mounts / and read or change anything on the server. Dockge's
login is therefore the only thing standing between the internet and root on
this machine. Its first load also creates the admin account, so whoever
reaches the page first owns the host. This guide puts HTTPS in front of it
first, and has you create the account immediately afterwards.
If you want a heavier, more established manager with users and roles, look at Portainer, or at Dokploy and CapRover if you want a deployment platform rather than a compose editor. The category lists the rest.
The upstream README lists the requirements as Docker 20+ (or Podman) on a major Linux distribution, with amd64, arm64 and armv7 builds, and publishes no RAM or disk figure.
In our install check (GCP e2-standard-2, Ubuntu 26.04, November 2026) Dockge
idled at about 109 MB of RAM, with Caddy adding about 12 MB
(docker stats --no-stream, about three minutes after a fresh start, no stacks
running and before the admin account was created), and the two images took
about 1.3 GB of Docker disk (docker system df; the Dockge image alone is
1.17 GB). The cost that matters is not
Dockge itself but the stacks you will run through it, so size the server for
those.
Install Docker and the Compose plugin by following Docker and Compose on Ubuntu, and confirm the versions:
docker --version
docker compose version
Open SSH plus the two ports Caddy will use. Dockge itself gets no public port:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
Docker publishes container ports by editing the firewall directly, which
bypasses ufw rules. That is why the compose file below binds Dockge's port
to 127.0.0.1, and why every stack you later create through Dockge should
publish its ports the same way ("127.0.0.1:8080:80") unless you really mean
to expose it.
Paid link — we earn a commission if you shop through it.
Upstream's layout is two directories: /opt/dockge for Dockge's own compose
file and data, and /opt/stacks for the stacks it manages. Its compose file
warns that the stacks path needs care: it must be a full path, and "Left
Stacks Path === Right Stacks Path", the same on the host and inside the
container. The reason is in the code: Dockge runs docker compose with the
stack's directory, as the container sees it, as the working directory, while
the command is executed by the host's Docker daemon. If the two paths differ,
relative bind mounts such as ./data in a stack resolve to the wrong
directory on the host. Dockge needs no secrets
of its own, so there is no .env to generate.
The compose file below is upstream's compose.yaml with two deliberate
changes: the image is pinned to 1.5.0 instead of the rolling 1 tag, and the
port is bound to loopback instead of 5001:5001.
sudo mkdir -p /opt/stacks
sudo install -d -o "$USER" -g "$USER" /opt/dockge
cd /opt/dockge
cat > docker-compose.yml <<'EOF'
services:
dockge:
image: louislam/dockge:1.5.0
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
Start it and wait for the web server. A log line reading No user, need setup followed by Listening on 5001 means it is ready and waiting for its
first account:
cd /opt/dockge
docker compose up -d
out=000
for i in $(seq 1 30); do
out=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5001/)
[ "$out" = "200" ] && break
sleep 2
done
docker compose ps
echo "loopback check: $out"
[ "$out" = "200" ] || false
Upstream's server code reads a few more environment variables if you need
them: DOCKGE_PORT (default 5001), DOCKGE_DATA_DIR (default ./data/),
DOCKGE_HOSTNAME, and DOCKGE_SSL_KEY / DOCKGE_SSL_CERT for built-in TLS,
which you do not need behind Caddy.
Create an A record for your hostname (say dockge.example.com) pointing at
the server. With no domain yet, an sslip.io name resolves to your server's
IP with no DNS setup, which is what this guide uses so every command runs as
written:
DOMAIN="dockge.$(curl -4s https://ifconfig.me).sslip.io"
echo "$DOMAIN"
Keep this shell session open (or re-run the line) for the rest of the guide, and replace the value with your real hostname when you have one.
Run Caddy as a container on the host network. It obtains and renews a Let's Encrypt certificate on its own (see Automatic HTTPS with Caddy) and proxies to the loopback port:
mkdir -p ~/caddy
cat > ~/caddy/Caddyfile <<EOF
$DOMAIN {
reverse_proxy 127.0.0.1:5001
}
EOF
docker rm -f caddy >/dev/null 2>&1 || true
docker run -d --name caddy --restart unless-stopped --network host \
-v ~/caddy/Caddyfile:/etc/caddy/Caddyfile:ro -v caddy_data:/data caddy:2
Dockge's interface runs over socket.io, so a 200 on / proves very little:
the page loads even when websockets are broken, and then the UI sits on a
spinner. Caddy's reverse_proxy supports WebSocket upgrades without extra
configuration and passes the Host header through unchanged, which matters
because Dockge's server rejects a browser connection whose Origin host does
not equal the request's Host. Check both from the real thing. The Dockge image
ships socket.io-client, so this opens a websocket-only connection through
Caddy over HTTPS from inside the container, then repeats it with a wrong
Origin to show the origin check works:
out=000
for i in $(seq 1 24); do
out=$(curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}' "https://$DOMAIN/") && [ "${out%% *}" = "200" ] && break
sleep 5
done
echo "HTTPS and certificate check: $out"
[ "${out%% *}" = "200" ] || false
cd /opt/dockge
docker compose exec -T -e DOMAIN="$DOMAIN" dockge node -e '
const { io } = require("socket.io-client");
function probe(origin) {
return new Promise((resolve) => {
const s = io("https://" + process.env.DOMAIN, {
transports: ["websocket"], reconnection: false,
extraHeaders: { Origin: origin },
});
const done = (r) => { s.close(); resolve(r); };
let needSetup = false;
s.on("setup", () => { needSetup = true; });
s.on("connect", () => setTimeout(() => done("websocket connected, " + (needSetup ? "server says: setup needed" : "an account already exists")), 1000));
s.on("connect_error", (e) => done("rejected: " + e.message));
setTimeout(() => done("timeout"), 8000);
});
}
(async () => {
const good = await probe("https://" + process.env.DOMAIN);
const bad = await probe("https://evil.example");
console.log("matching Origin: " + good);
console.log("mismatched Origin: " + bad);
process.exit(good.startsWith("websocket connected") && bad.startsWith("rejected") ? 0 : 1);
})();
'
A second number of 0 on the certificate line means it verified. The
check passes whether or not an account exists yet: before first-run it reports
setup needed, the server's own signal that nobody has claimed the host (which
is the state you are about to close), and afterwards an account already exists, so you can re-run it any time.
Open https://dockge.example.com (your hostname) now, before you do
anything else. The first load asks you to create the admin account. In
Dockge's code that is a one-shot: the setup call creates the first user, and
once a user exists any later attempt answers "Dockge has been initialized. If
you want to run setup again, please delete the database." Passwords that the
check-password-strength library rates "Too weak" are refused (the message
asks for letters and numbers and at least 6 characters), so use a long
password from a password manager; this login is root on your server.
Two things to know afterwards:
IP=172.18.0.1 on a login through Caddy) rather than the
visitor's IP. The server can read X-Forwarded-For, but
only when a trustProxy setting is on, and the 1.5.0 settings page has no
control for it.The global console, a shell inside the Dockge container, is off by default.
The server reads DOCKGE_ENABLE_CONSOLE (default false) and refuses the
console with "Console is not enabled." unless it is true. Leave it off.
The per-container terminal in the stack view is a separate handler with its
own path, so a logged-in user can still open a shell in any container Dockge
manages.
Stacks you create in the UI are plain compose.yaml files under
/opt/stacks/<name>/. To adopt an existing project, upstream's FAQ says to
stop it, move its compose file to /opt/stacks/<name>/compose.yaml, and
choose Scan Stacks Folder from the top-right menu.
Dockge's own state is small: /opt/dockge/data holds a SQLite database
(dockge.db, with its -wal and -shm companions) with the account and a
generated JWT secret, and /opt/stacks holds your compose files, their .env
files and any relative bind-mount directories inside each stack folder. The
tarball also includes Dockge's docker-compose.yml. Back up both together. The database runs
in WAL mode, so stop the Dockge container for the few seconds the archive
takes; that does not touch the stacks it manages, which are separate
containers:
cd /opt/dockge
mkdir -p ~/dockge-backup
docker compose stop dockge
sudo tar czf ~/dockge-backup/dockge-$(date +%F).tgz -C / opt/dockge opt/stacks
docker compose start dockge
ls -lh ~/dockge-backup
Dockge is stopped during the copy, but the stacks keep running, so anything
they write under /opt/stacks (a database in a relative bind mount, say) is
copied live and may be inconsistent: stop that stack first for a clean copy.
The archive does not include named Docker volumes or bind mounts outside
/opt/stacks; back those up with each application's own instructions. It also
leaves out ~/caddy/Caddyfile, so a restored Dockge listens on loopback only
until you re-run the HTTPS section. Copy the archive off the server on a
schedule.
To restore, unpack it at / on a server with the same paths, run docker compose up -d in /opt/dockge, and re-run the HTTPS section. Restoring files
does not start your stacks: start them from the Dockge interface (or docker compose up -d in each stack folder). We tested this on the verification
server: after wiping /opt/dockge, /opt/stacks and the containers and
unpacking the archive, the account and a stack's files, including its
bind-mount data, were back.
Upstream's update instructions are docker compose pull && docker compose up -d in the Dockge directory. With a pinned tag you change the version
first, read the release notes on the project's GitHub releases page, and take
the backup above before you do.
cd /opt/dockge
sed -i 's|louislam/dockge:1.5.0|louislam/dockge:NEW_VERSION|' docker-compose.yml
docker compose pull dockge
docker compose up -d dockge
docker compose logs --tail 20 dockge
The page loads but the interface spins forever. Websockets are not
getting through. Re-run the websocket check above. If you put a different
proxy in front, it must upgrade connections for /socket.io/ and pass the
original Host header: with a mismatched Origin, the server logs
Origin (...) does not match host (...) and refuses the socket.
A login page appears but you never created an account. With a user in the
database the interface shows the login page, and the setup page only appears
when the server says no user exists (the "Dockge has been initialized" message
is what a stale setup form gets back). Someone else reached the setup page first. Treat the host as compromised: stop Dockge,
review docker ps and /opt/stacks, and rebuild the server if anything is
unfamiliar. Deleting /opt/dockge/data resets the setup form, but it does
not tell you what the other person did.
New stacks end up in the wrong folder. The stacks path differs between
host and container. /opt/stacks:/opt/stacks and
DOCKGE_STACKS_DIR=/opt/stacks must agree exactly.
Port 5001 is reachable from the internet. The port line lost its
127.0.0.1: prefix. Fix the compose file, docker compose up -d, then check
that ss -tln | grep 5001 shows 127.0.0.1.
Certificate never issues. That is a Caddy and DNS problem rather than a
Dockge one: confirm the A record resolves (dig +short dockge.example.com)
and that ports 80 and 443 are reachable. Look at docker logs caddy.
You are done when https://dockge.example.com loads with a valid certificate,
the websocket check above printed websocket connected, you have created the
admin account with a strong password, port 5001 is bound only to 127.0.0.1,
and an archive of /opt/dockge and /opt/stacks is landing off the server.
Confirm the port binding:
sudo ss -tlnp | grep ':5001 '
From here, move your other compose projects into /opt/stacks. If you want
uptime checks on them, Uptime Kuma has its own
deploy guide and is easy to add as a
Dockge stack.
We estimate about 20 minutes of hands-on time for "How to Deploy Dockge on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy Dockge on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Nov 2026).