If you've been running a homelab for more than a few months, you've probably got a folder full of docker-compose.yml files scattered across different directories, half of them edited by hand at 11pm and never backed up anywhere. Dockge fixes that specific problem. It's a small, fast web UI built around one idea: your Docker Compose stacks are just YAML files, so let people edit, deploy, and monitor that YAML from a browser instead of SSH-ing in every time.
This guide walks you through installing Dockge inside an LXC container on Proxmox VE 9.2. You don't need any Docker experience going in — we'll explain each concept as it shows up, and by the end you'll have a working stack manager plus enough understanding to troubleshoot it yourself when something breaks.
What You Will Learn
By the end of this tutorial you'll know how to:
- Create a Debian 13 LXC container on Proxmox VE with the settings Docker actually needs to run inside it
- Install Docker Engine and the Docker Compose plugin inside that container
- Deploy Dockge itself using its official compose file
- Create and manage your first Docker Compose stack through Dockge's web interface
- Recognize and fix the handful of errors almost everyone hits on their first try
What Is This Feature?
Dockge is an open-source, self-hosted web application for managing Docker Compose stacks. It's built by the same developer behind Uptime Kuma, and it shows — the interface is clean, the YAML editor has syntax highlighting, and deploying a stack updates in real time in your browser instead of leaving you staring at a spinner.
Before we go further, a couple of terms worth nailing down if you're new to this:
Docker is a tool that packages an application together with everything it needs to run — libraries, dependencies, a mini filesystem — into a "container." Containers start in seconds and don't interfere with each other, which is why homelabbers run dozens of them on a single small server.
Docker Compose is a way of describing one or more containers, their networking, and their storage in a single YAML file, so you can spin up a whole application stack with one command instead of typing a dozen docker run flags from memory.
Dockge doesn't replace Docker or Compose. It sits on top of them. Every stack you create in Dockge is a real docker-compose.yml file sitting in a real folder on disk — you can still edit it with a text editor over SSH if you want to. Dockge just gives you a nicer way to do it, plus a live terminal view of the deploy logs so you can actually see what went wrong when a container fails to start.
Why Would You Use It?
Most people asking this have already used Portainer, so it's worth being direct about the difference. Portainer is a full container management platform — it can manage individual containers, images, volumes, networks, Swarm clusters, the works. Dockge does one thing: Compose stacks. That narrower focus is the whole appeal.
A few reasons people switch, or run both:
- The stack editor feels like editing a file, not clicking through five tabs of form fields to reconstruct what a compose file already says
- Deploy logs stream live in the browser, so you see the actual
docker compose upoutput as it happens - It's genuinely lightweight — the container itself uses well under 100 MB of RAM at idle
- Stacks live as plain files in
/opt/stacks, so there's no proprietary database to lose if the app itself ever breaks
Honestly, if you only run two or three containers total, you probably don't need Dockge or Portainer — SSH and a text editor will do fine. This tool starts paying for itself once you're juggling ten-plus stacks and can't remember which folder has which YAML file anymore.
Prerequisites
Before starting, make sure you have:
- A working Proxmox VE 9.x host (this guide was written and tested against 9.2, but the steps are the same back through 8.x)
- A Debian 13 (Trixie) LXC template downloaded, or Debian 12 if that's what you already have available
- At least 2 GB of RAM and 8 GB of disk space allocated to the container — give it more disk if you plan on running several stacks with their own images, since those add up fast
- Basic comfort typing commands into a terminal — we'll explain every one, but you should know how to open the container console from the Proxmox web UI
Step-by-Step Tutorial
Step 1: Create the LXC container
In the Proxmox web UI, click Create CT in the top right. Give it a hostname like dockge, set a root password, and on the Template screen pick debian-13-standard. On the Resources screen, 2 CPU cores and 2048 MB of RAM is a comfortable starting point — you can always bump these later without reinstalling anything.
Leave the container as unprivileged. It's the safer default, and Docker runs fine inside an unprivileged container as long as you flip two settings in the next step.
Step 2: Enable nesting and keyctl
Docker needs to create its own nested namespaces and cgroups, which an unprivileged LXC container blocks by default for security reasons. You need to turn two features on before Docker will even start.
After the container is created, go to Options → Features in the Proxmox UI and enable both Nesting and keyctl. If you'd rather do it from the host shell, this one-liner does the same thing — just swap in your container's actual ID:
pct set 105 --features nesting=1,keyctl=1Skip this step and Docker's installer will run without errors, but the dockerd service will refuse to start, or containers will fail with permission errors the moment they try to start their own process namespace. It's the single most common reason Docker "doesn't work" in an LXC container.
Step 3: Start the container and update it
Start the container from the Proxmox UI, then open its console. First, pull the latest package lists and apply any pending updates:
apt update && apt upgrade -yThen install curl, since Debian's minimal template doesn't always include it and you'll need it for the next two steps:
apt install -y curlStep 4: Install Docker
Docker publishes an official convenience script that detects your distribution and installs the right packages automatically. It's the fastest reliable path on a fresh Debian container:
curl -fsSL https://get.docker.com | shThis takes about a minute on a typical homelab connection. When it finishes, confirm both Docker and the Compose plugin installed correctly:
docker --version
docker compose versionYou should see version output for both — something like Docker version 27.x and Docker Compose version v2.x. If either command isn't found, go back and confirm nesting was actually enabled before you ran the install script.
Step 5: Set up Dockge's directories and compose file
Dockge keeps two things separate on disk: its own application data, and the folder where all your future stacks will live. Create both now:
mkdir -p /opt/stacks /opt/dockge
cd /opt/dockgeNow create the compose file that will run Dockge itself. Open a new file with nano compose.yaml and paste this in:
services:
dockge:
image: louislam/dockge:1
container_name: dockge
restart: unless-stopped
ports:
- 5001:5001
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /opt/dockge/data:/app/data
- /opt/stacks:/opt/stacks
environment:
- DOCKGE_STACKS_DIR=/opt/stacksThat volume mount of /var/run/docker.sock is the important one — it's how Dockge talks to the Docker daemon on the host it's running in. Without it, Dockge has no way to actually start or stop containers; it would just be a YAML editor with no teeth.
Step 6: Start Dockge
From inside /opt/dockge, bring the stack up:
docker compose up -dThe -d flag runs it detached, so it keeps running after you close the terminal. Give it about ten seconds, then check that the container is actually up:
docker psYou should see a container named dockge with status Up.
Step 7: Open the web interface
Find your container's IP address — it's shown on the Summary tab in the Proxmox UI, or run ip a inside the container. Then open http://<container-ip>:5001 in your browser.
The first time you visit, Dockge asks you to create an admin account. Pick a real password here — this account has full control over every Docker container Dockge can reach, which after this setup means everything on the host.
Step 8: Deploy your first stack
Click + Compose in the Dockge sidebar. Give the stack a name (this becomes the folder name under /opt/stacks, so keep it lowercase with no spaces), then paste in a compose definition. A harmless test stack to confirm everything works end to end:
services:
whoami:
image: traefik/whoami
ports:
- 8080:80
restart: unless-stoppedClick Deploy. You'll see the build log stream live in the browser, and within a few seconds the stack shows as Running. Visit http://<container-ip>:8080 and you should see a small text response confirming the container is alive. Delete this test stack once you've confirmed it works — you don't need it running long-term.
Commands Explained
| Command | What it does |
|---|---|
pct set 105 --features nesting=1,keyctl=1 | Enables the LXC features Docker needs to manage its own namespaces from inside an unprivileged container |
curl -fsSL https://get.docker.com | sh | Downloads and runs Docker's official install script, which detects Debian and installs Docker Engine plus the Compose plugin |
docker compose up -d | Reads the compose.yaml in the current directory and starts every service it defines, detached from the terminal |
docker ps | Lists every currently running container, along with its status and exposed ports |
docker compose logs -f dockge | Streams Dockge's own container logs live, useful when the web UI won't load |
Common Errors
A few messages come up often enough that they're worth calling out by name before you hit them.
"Cannot connect to the Docker daemon at unix:///var/run/docker.sock" — this almost always means nesting wasn't enabled before Docker was installed, or the container was rebooted and the daemon didn't come back up cleanly. Check systemctl status docker inside the container first.
Port 5001 already in use — happens if you're also running Uptime Kuma, since it defaults to the same port range on some setups, or if you tried to deploy Dockge twice. Change the left-hand side of the port mapping in compose.yaml, for example 5002:5001, and redeploy.
Stack shows "Exited" immediately after deploy — read the deploy log Dockge shows you before assuming it's a Dockge problem. Nine times out of ten it's a typo in the pasted YAML, not Dockge itself misbehaving.
Troubleshooting
If the web UI won't load at all, start from the container outward rather than guessing:
- Confirm the container is running from the Proxmox Summary tab
- Confirm Docker itself is healthy:
systemctl status docker - Confirm the Dockge container specifically is up:
docker ps | grep dockge - Check its logs for startup errors:
docker compose logs -f dockgefrom/opt/dockge - Double-check the container's IP hasn't changed — DHCP leases do expire, and a static IP or DHCP reservation avoids this headache entirely
If a specific stack won't deploy but Dockge itself is fine, the fix is almost always in the YAML, not the tool. Paste the compose file into a validator or just read it line by line for indentation — YAML is whitespace-sensitive, and a stray tab character will break a deploy with an error message that doesn't obviously point at whitespace.
Best Practices
A few habits worth building in from day one:
- Don't expose port 5001 to the internet directly. Put it behind a VPN like Tailscale or WireGuard, or behind a reverse proxy with authentication in front of it. Dockge's admin account has no built-in two-factor option, and it controls every container on the box.
- Back up the whole container, not just individual stack folders. A scheduled vzdump job against the container ID captures
/opt/stacksand/opt/dockge/datatogether, which is what you actually need to restore a working setup. - Keep stack names short and descriptive — you'll be reading them in a sidebar list for months, and "stack47" tells you nothing six weeks from now.
- Update Dockge itself occasionally by pulling a new image tag and redeploying its own stack, the same way you'd update any other stack it manages.
Frequently Asked Questions
Is Dockge free?
Yes. It's fully open source under the MIT license, with no paid tier or feature gating.
Does Dockge replace Portainer?
Not entirely. Portainer manages individual containers, images, and volumes in detail; Dockge focuses purely on Compose stacks. Plenty of people run both side by side without conflict.
Can I run Dockge and Portainer in the same container?
Yes, as long as they're on different ports. They both talk to the same Docker socket without stepping on each other.
Do I need a privileged LXC container for this?
No. Everything in this guide runs in an unprivileged container once nesting and keyctl are enabled.
Does updating Dockge affect my existing stacks?
No. Your stacks are independent containers managed through the Docker socket. Updating or even reinstalling Dockge doesn't stop or modify them.
Conclusion
Once Dockge is running, the actual day-to-day workflow gets a lot smaller than this guide makes it look. You'll spend maybe ten minutes on this initial setup, and after that, adding a new stack is a matter of pasting YAML into a browser tab and clicking Deploy. If you've been maintaining compose files by hand across a dozen SSH sessions, this is the point where that stops being necessary.