Self-Hosting Dockge: Lightweight Docker Compose Manager

If you’ve been managing Docker Compose stacks by SSH-ing into servers and editing YAML files in nano, Dockge is about to change your life. Created by the same developer behind Uptime Kuma, Dockge is a reactive, web-based Docker Compose manager that keeps things simple — no abstraction layers, no proprietary formats, just your compose.yaml files with a clean UI on top.

Unlike Portainer (which wraps everything in its own API) or Coolify (which is a full PaaS), Dockge stays close to the metal. Your compose files live on disk exactly where you’d expect them, and you can still use docker compose commands directly. Dockge just gives you a nicer way to do it.

Why Dockge Over the Alternatives?

Dockge hits the sweet spot: more capable than terminal tools, lighter than Portainer, and it never locks you into its ecosystem.

Prerequisites

• A Linux server (Ubuntu 22.04+, Debian 12+, or similar)
• Docker Engine 20.10+ and Docker Compose v2
• At least 512MB free RAM
• A directory for your compose stacks (we’ll use /opt/stacks)

Installation

Dockge keeps things straightforward. Create the directories and drop in a compose file:

# Create directories
sudo mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge

Create the compose.yaml:

services:
  dockge:
    image: louislam/dockge:1
    container_name: dockge
    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

Start it up:

docker compose up -d

Open http://your-server-ip:5001 in your browser. You’ll be prompted to create an admin account on first visit.

Important: The Stacks Directory

The DOCKGE_STACKS_DIR path is where Dockge looks for and creates compose stacks. Each stack gets its own subdirectory:

If you already have compose files elsewhere, either move them into this directory or symlink them.

Creating Your First Stack

From the Dockge UI:

1. Click "+ Compose" in the top left
2. Give your stack a name (e.g., uptime-kuma)
3. Use the interactive editor to write your compose YAML:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

4. Click “Deploy”

The editor provides syntax highlighting and validation, so you’ll catch YAML errors before deploying. The real-time log output shows exactly what docker compose up is doing.

Converting docker run Commands

One of Dockge’s killer features: paste a docker run command and it converts it to compose format. Click the “Convert” button, paste something like:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_SCHEDULE="0 4 * * *" \
  --restart unless-stopped \
  containrrr/watchtower

Dockge produces the equivalent compose.yaml automatically. No more manually translating flags to YAML keys.

Managing Existing Stacks

Already have compose files running? Move them into the stacks directory:

# Stop the existing stack
cd /path/to/existing/stack
docker compose down

# Move to Dockge's stacks directory
sudo mv /path/to/existing/stack /opt/stacks/stack-name

# Restart from new location
cd /opt/stacks/stack-name
docker compose up -d

Dockge auto-discovers anything in the stacks directory on refresh. No import step required.

Multi-Host Management with Agents

Since version 1.4, Dockge supports managing stacks across multiple Docker hosts from a single UI. On each remote host, run Dockge in agent mode:

services:
  dockge-agent:
    image: louislam/dockge:1
    container_name: dockge-agent
    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

Then in your main Dockge instance, add the remote host via Settings → Agents. Enter the agent’s hostname/IP and port. Once connected, you can manage all hosts from one dashboard.

This is ideal for setups with multiple servers — a NAS, a cloud VPS, and a home lab machine, all managed from one place.

Reverse Proxy Setup

Running Dockge behind a reverse proxy gives you HTTPS and a clean URL.

Caddy

Nginx

server {
    listen 443 ssl http2;
    server_name dockge.example.com;

    ssl_certificate /etc/ssl/certs/dockge.crt;
    ssl_certificate_key /etc/ssl/private/dockge.key;

    location / {
        proxy_pass http://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /socket.io/ {
        proxy_pass http://127.0.0.1:5001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Note: Dockge uses WebSockets for its reactive UI, so make sure your proxy supports WebSocket upgrades (the /socket.io/ block in Nginx). Caddy handles this automatically.

Updating Dockge

Dockge can’t update itself (it would need to restart its own container), so update from the command line:

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

Your stacks and data persist across updates since everything is stored in mounted volumes.

Backup and Restore

Dockge’s file-based approach makes backups trivial:

# Backup everything
tar czf dockge-backup-$(date +%Y%m%d).tar.gz \
  /opt/dockge/data \
  /opt/stacks

# Restore
tar xzf dockge-backup-20260320.tar.gz -C /
cd /opt/dockge && docker compose up -d

Since stacks are plain compose files, you can also version-control your /opt/stacks directory with Git:

cd /opt/stacks
git init
git add -A
git commit -m "Initial stack snapshot"

This gives you rollback capability for any compose changes.

Troubleshooting

Dockge Can’t Connect to Docker

Make sure the Docker socket is mounted and the Dockge container has access:

# Check socket exists
ls -la /var/run/docker.sock

# Verify Docker is running
sudo systemctl status docker

Stacks Not Appearing

• Verify stacks are in the correct directory (matching DOCKGE_STACKS_DIR)
• Each stack needs its own subdirectory with a compose.yaml (not docker-compose.yml — Dockge expects the modern filename by default)
• Click the refresh button in the UI

WebSocket Connection Failed

If the UI loads but shows “Disconnected”:

• Check that your reverse proxy forwards WebSocket connections
• Ensure nothing is blocking the /socket.io/ path
• Try accessing Dockge directly by IP:port to confirm it works without the proxy

High Memory Usage

Dockge itself is lightweight (~60MB), but if you’re managing many stacks, Docker itself may consume significant memory. Check with:

docker stats --no-stream

Permission Issues with Stacks

If Dockge can’t create or modify files in the stacks directory:

# Ensure the directory is writable
sudo chown -R 1000:1000 /opt/stacks

Tips for Power Users

Environment files: Keep .env files alongside your compose.yaml in each stack directory. Dockge respects them just like docker compose does.

Labels for organization: Add labels to your services for better organization with other tools like Homepage or Traefik:

services:
  myapp:
    image: myapp:latest
    labels:
      - "homepage.group=Media"
      - "homepage.name=My App"

Terminal access: Use Dockge’s built-in web terminal to exec into containers without SSH-ing into your server first. Click any running container and hit the terminal icon.

Compose profiles: Dockge supports Docker Compose profiles, so you can define optional services in a stack and toggle them from the UI.

Conclusion

Dockge is what Docker Compose management should feel like — a thin, respectful layer on top of your existing workflow. It doesn’t try to replace docker compose, it just makes it more pleasant. Your files stay where they are, your commands still work, and you get a clean web UI with real-time feedback.

For self-hosters who want something more visual than the terminal but less opinionated than Portainer, Dockge is the perfect middle ground. And at ~60MB of RAM, there’s really no reason not to run it.

Useful Links:

• Dockge GitHub
• Docker Hub
• Uptime Kuma (same developer)
• Compose File Reference