How to Visually Manage Docker Compose Services with Dockge: A Practical Guide

How to Visually Manage Docker Compose Services with Dockge: A Practical Guide

If you're like me, you've deployed a bunch of services on your server using docker compose—blogs, databases, reverse proxies, log collectors... Every time you need to tweak a config, check logs, or restart a container, you have to SSH in, cd to the right directory, and run docker compose up -d or docker compose logs -f. It works fine with a few services, but as the number grows, remembering where each compose.yaml lives becomes a headache. Not to mention trying to spot errors in a terminal flooded with scrolling logs.

That's why I've been looking for a tool that keeps the local file-management benefits of compose while offering a friendly web interface. I used Portainer for a long time, but its stack management felt clunky—deployment would spin for ages without clear feedback, and error messages were often cryptic.

Then I found Dockge. Developed by louislam (creator of Uptime Kuma), it has a clear mission: a dedicated visual manager for Docker Compose stacks. It's not a bloated all-in-one Docker platform; it focuses on making high-frequency tasks like editing compose.yaml, toggling services, and reading logs as smooth as possible.

In this guide, you'll learn how to:

1. Deploy Dockge on your server in under 3 minutes.
2. Manage a Docker Compose project via its Web UI (using Nginx + a static site as an example).
3. Handle daily ops: online config editing, live log monitoring, and one-click image updates.
4. Avoid common pitfalls.

By the end, you'll be ready to make Dockge your go-to Docker management tool. Let's dive in.

Prerequisites

Before we begin, ensure your environment meets these requirements:

• Docker 20+ (or Podman) is mandatory.
• OS: Ubuntu / Debian Bullseye+ / CentOS / Fedora / ArchLinux are supported.
  • Raspbian/Debian Buster or older are not supported.
  • Windows is currently not supported.
• Architectures: armv7, arm64, amd64 (wide coverage).
• Basic familiarity with Docker Compose and compose.yaml.

Check your setup:

docker --version
docker compose version

If docker compose isn't found, install Compose V2 (built into Docker 20.10+).

Quick Start: Deploying Dockge

Dockge itself is a Docker Compose project, so deploying it demonstrates exactly how it manages stacks. We'll follow the official README flow with step-by-step explanations.

Step 1: Create Required Directories

mkdir -p /opt/stacks /opt/dockge
cd /opt/dockge

• /opt/stacks: The root folder for all your managed compose projects. Dockge is "file-based," meaning all compose.yaml files live here as real files, not locked in a database. You can still manage them directly via CLI if needed.
• /opt/dockge: Stores Dockge's own configuration and runtime data.

Step 2: Fetch the compose.yaml

curl https://raw.githubusercontent.com/louislam/dockge/master/compose.yaml --output compose.yaml

This pulls the official configuration. You can also use the interactive generator at https://dockge.kuma.pet to customize ports and stack paths before downloading.

Step 3: Launch

docker compose up -d

(Note: Use docker-compose up -d for legacy V1, or ensure podman-docker is installed for Podman users.)

Once running, visit http://<your-server-ip>:5001 in your browser.

Why port 5001? The author intentionally avoids common ports like 80 or 8080 to reduce conflicts. You can change it later in the compose file if needed.

Updating Dockge: Future upgrades only take two commands:

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

Practical Example: Deploy an Nginx Website

Let's deploy a simple Nginx static site to experience Dockge's core workflow.

Create a New Stack

In the Dockge UI, click to add a new stack and fill in the following:

• Stack Name: my-website (maps to /opt/stacks/my-website/)
• compose.yaml Editor: Paste this on the right panel:

services:
  nginx:
    image: nginx:alpine
    container_name: my-nginx
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html

Breakdown:

• Uses the lightweight nginx:alpine image.
• Names the container my-nginx for easy identification.
• Maps host port 8080 to container port 80.
• Mounts ./html to Nginx's default web root.

Click "Save", then click "Up". Dockge will pull the image, create the container, and start the service with real-time progress and logs.

Deploy the Frontend Page

Since we mounted ./html, create a test page on the host:

mkdir -p /opt/stacks/my-website/html
echo '<h1>Hello from Dockge-managed Nginx!</h1>' > /opt/stacks/my-website/html/index.html

Visit http://<your-ip>:8080 to see the live page.

Online Editing & Hot Reload

Want to change the title or switch ports? Edit the compose.yaml directly in Dockge's UI. For example, change 8080:80 to 9090:80, save, and click "Restart". The changes apply instantly—no need to SSH or type manual commands.

View Live Logs

Dockge includes a built-in Web Terminal and log viewer. Click your stack to access:

• Container status (Running / Stopped)
• Real-time log streaming
• One-click restart/stop buttons

This makes debugging incredibly straightforward—no more guessing with docker compose logs -f --tail=200.

Advanced Features Worth Knowing

1. docker run to compose.yaml Converter
Paste a long docker run command into the built-in converter, and Dockge auto-generates the equivalent compose file. Perfect for migrating scattered single-container commands to a standardized format.

2. Multi-Agent Support (v1.4.0+)
Manage Compose stacks across multiple Docker hosts from a single UI. No more jumping between SSH sessions.

3. Permission Management (PUID/PGID)
If you don't run Docker as root, add these environment variables to your compose file:

environment:
  - DOCKGE_STACKS_DIR=/opt/stacks
  - PUID=1000
  - PGID=1000

Both must be set together to control file ownership. Otherwise, files default to root, which often causes permission denied errors during volume mounts.

FAQs & Common Pitfalls

Q1: How do I import existing Compose projects?
Dockge doesn't auto-scan your filesystem. To import:

1. Stop the existing service via CLI or Portainer.
2. Move its compose.yaml to /opt/stacks/<project-name>/compose.yaml.
3. Click "Scan Stacks Folder" in Dockge's top-right menu.
4. It will appear in your dashboard.

Q2: Does it conflict with Portainer?
No. They serve different purposes and can coexist. Use Portainer for raw container/network/volume management, but Dockge shines for Compose-heavy workflows where you want direct file visibility and fast iteration.

Q3: Can it manage single docker run containers without compose files?
Dockge's philosophy is "everything is compose." For standalone containers, Portainer or Docker CLI is better. Dockge actively encourages adopting compose.yaml as a best practice for reproducibility.

Q4: Why must host and container volume paths match?
The README explicitly warns about this:

## ✔️ Correct
- /opt/stacks:/opt/stacks
## ❌ Wrong (mismatched paths)
- /my-data:/opt/app/data  ← May write data to unexpected locations

Dockge needs to track file mappings accurately for its UI operations. Keeping paths consistent prevents data from being written to unexpected host directories.

Conclusion

We've covered:

1. Deploying Dockge (3 commands)
2. Using it to run an Nginx site (full create → start → edit → log workflow)
3. Permissions, imports, and how it compares to Portainer

My take: If you manage 3+ self-hosted services with Docker Compose, Dockge significantly reduces daily operational overhead. It doesn't try to replace Portainer; it just nails Compose management—keeping files accessible, offering a clean UI, and providing instant feedback.

Next steps:

• Gradually migrate existing projects to Dockge.
• Use the docker run → compose converter to standardize scattered commands.
• Pair it with a reverse proxy (like Nginx Proxy Manager or Traefik) for a unified private dashboard.

The GitHub Discussions community is active, and the author responds promptly. Feel free to share your experiences below!

🔗 Project: https://github.com/louislam/dockge