Dockge: Simple Docker Compose Management

Overview

Dockge is a lightweight, self-hosted Docker Compose stack manager that brings elegant simplicity to container orchestration. Created by Louis Lam (the developer behind Uptime Kuma), Dockge focuses on doing one thing exceptionally well: managing Docker Compose stacks through an intuitive web interface.

Unlike heavyweight alternatives, Dockge embraces the philosophy that your docker-compose.yml files are the source of truth. It doesn’t abstract away Docker Compose - it enhances it. You get a beautiful interface for managing stacks while maintaining full control over your compose files, which remain editable both through the UI and directly on the filesystem.

What you’ll learn:

• Deploy Dockge on your homelab server in under 15 minutes
• Create and manage Docker Compose stacks through a web UI
• Edit compose files with syntax highlighting and validation
• Monitor container logs and resource usage in real-time
• Compare Dockge with Portainer and choose the right tool
• Implement best practices for stack organization
• Leverage Dockge’s unique features for efficient management

Why Dockge?

Instead of learning complex UIs or fighting with tools that hide your compose files, Dockge gives you a clean, React-based interface that respects your existing workflow. Edit your stacks in the browser with syntax highlighting, start/stop services with one click, and view live logs - all while your compose files remain exactly where you put them.

---

Prerequisites

Before starting, ensure you have:

• Docker installed on your host system (version 20.10.x or newer)
• Docker Compose (V2 recommended, bundled with modern Docker)
• Basic understanding of Docker Compose syntax
• Hardware requirements:
  • Minimum 256 MB RAM (512 MB recommended)
  • 5 GB storage for application data
  • Network access on port 5001
• Web browser supporting modern JavaScript (Chrome, Firefox, Safari, Edge)
• Text editor for editing configuration files (optional, since Dockge has built-in editor)

If you don’t have Docker installed yet, follow our Docker Installation Guide first.

---

Understanding Dockge Fundamentals

What is Dockge?

Dockge is a fancy, easy-to-use, reactive self-hosted Docker Compose stack manager. Let’s break that down:

• Fancy: Beautiful, modern React UI with smooth animations
• Easy-to-use: Minimal learning curve, intuitive controls
• Reactive: Real-time updates without page refreshes
• Self-hosted: Runs on your infrastructure, no cloud dependencies
• Stack manager: Focused specifically on Docker Compose, not trying to do everything

Core Philosophy

Dockge takes a refreshingly different approach from traditional container management tools:

1. File-based management: Your compose files live on the filesystem, editable outside Dockge
2. Simplicity over features: Does stack management exceptionally well, nothing more
3. Developer-friendly: Built by developers, for developers
4. Transparency: No hidden configurations or proprietary formats
5. Lightweight: Minimal resource footprint (~50 MB RAM typical usage)

Key Features

• Stack Management: Create, start, stop, restart, delete stacks with one click
• Interactive Editor: Built-in compose file editor with syntax highlighting
• Live Logs: Real-time container log streaming with search
• Resource Monitoring: CPU, memory, and network usage per container
• Multiple Compose Files: Manage multiple docker-compose.yml files as separate stacks
• Terminal Access: Execute commands inside containers via web terminal
• Agent Mode: Manage remote Docker hosts (experimental)
• Responsive Design: Works beautifully on desktop, tablet, and mobile

---

Dockge vs. Portainer: Choosing the Right Tool

Both Dockge and Portainer manage Docker containers, but they target different use cases:

Comparison Matrix

When to Choose Dockge

Perfect for:

• You primarily use Docker Compose (not Swarm/Kubernetes)
• You want minimal overhead and maximum simplicity
• You prefer editing compose files directly
• Your homelab is single-host or simple multi-host
• You value speed and responsiveness over features
• You’re coming from command-line Docker Compose

Example use case: “I have 10-20 compose stacks on a single server. I want a clean UI to start/stop services, view logs, and occasionally edit compose files. I don’t need templates, Kubernetes, or enterprise features.”

When to Choose Portainer

Perfect for:

• You manage Kubernetes clusters or Docker Swarm
• You need role-based access control for teams
• You want application templates for quick deployment
• You’re managing 5+ Docker hosts
• You need GitOps integration for automated deployments
• You require advanced networking features

Example use case: “I manage 5 Docker hosts, 2 Kubernetes clusters, and want to give family members limited access to specific services. I deploy from GitHub repositories and need audit logs.”

Can You Use Both?

Yes! Many homelabbers run both:

• Dockge for daily stack management (fast, lightweight)
• Portainer for advanced features (templates, multi-host overview)

They complement each other well since Dockge is so lightweight it doesn’t interfere with Portainer.

---

Installation and Initial Setup

Method 1: Docker Compose (Recommended)

This is the official installation method from Dockge documentation.

Step 1: Create Dockge directory structure

Dockge needs a directory to store its data and a directory to store your compose stacks:

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

# Navigate to Dockge directory
cd /opt/dockge

Why /opt?

• /opt is the standard Linux location for optional application software
• Keeps your stacks organized and separate from system files
• Easy to backup and migrate

Step 2: Create compose.yaml for Dockge itself

Create /opt/dockge/compose.yaml:

version: "3.8"

services:
  dockge:
    image: louislam/dockge:1
    container_name: dockge
    restart: unless-stopped
    ports:
      - "5001:5001"
    volumes:
      # Docker socket for container management
      - /var/run/docker.sock:/var/run/docker.sock
      # Dockge data (settings, users)
      - ./data:/app/data
      # Stacks directory (your compose files)
      - /opt/stacks:/opt/stacks
    environment:
      # Tell Dockge where stacks are located
      - DOCKGE_STACKS_DIR=/opt/stacks

Configuration explanation:

• image: louislam/dockge:1 - Uses Dockge v1.x (automatically updates to latest 1.x)
• ports: 5001:5001 - Web UI accessible on port 5001
• /var/run/docker.sock - Access to Docker daemon for managing containers
• ./data - Dockge’s database and settings
• /opt/stacks - Your compose stacks (editable outside Dockge)
• DOCKGE_STACKS_DIR - Tells Dockge where to find/create stacks

Step 3: Deploy Dockge

# Start Dockge
docker compose up -d

# Verify deployment
docker compose ps

# Check logs
docker compose logs -f

You should see output like:

dockge  | Server Type: Single Server
dockge  | Stacks Directory: /opt/stacks
dockge  | Base URL: http://localhost:5001
dockge  | Listening on http://0.0.0.0:5001

Step 4: Access Dockge

Open your web browser and navigate to:

http://localhost:5001

Or from another computer on your network:

http://<your-server-ip>:5001

Initial Configuration

Create admin account:

On first visit, you’ll be prompted to create an admin user:

• Username: admin (or your preference)
• Password: Create a strong password (16+ characters recommended)

Important: Store credentials in a password manager (Bitwarden, 1Password, KeePass).

Unlike some tools, Dockge is single-user by design - it’s built for personal homelabs, not multi-user teams.

---

Creating and Managing Stacks

Your First Stack: Nginx Web Server

Let’s create a simple stack to understand the workflow.

Step 1: Create new stack

1. Click ”+ Compose” button in top-right
2. Enter stack name: nginx-test
3. The compose editor opens with a template

Step 2: Define the compose file

Replace the template with this nginx example:

version: "3.8"

services:
  nginx:
    image: nginx:alpine
    container_name: nginx-test
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    environment:
      - TZ=America/New_York

Step 3: Create HTML content

Dockge automatically creates a directory at /opt/stacks/nginx-test/. You can add files there:

# Create HTML file
echo '<h1>Hello from Dockge!</h1>' > /opt/stacks/nginx-test/html/index.html

Or create it through Dockge’s file browser (if available in your version).

Step 4: Deploy the stack

Click “Start” button at the top.

Dockge will:

1. Save the compose file to /opt/stacks/nginx-test/compose.yaml
2. Run docker compose up -d in that directory
3. Show real-time deployment logs

Step 5: Verify deployment

Visit http://localhost:8080 - you should see “Hello from Dockge!”

Stack Management Operations

Once deployed, you can:

View container status:

• Green indicator = Running
• Red indicator = Stopped
• Yellow indicator = Unhealthy

Control buttons:

• Start: docker compose up -d
• Stop: docker compose stop
• Restart: docker compose restart
• Down: docker compose down (removes containers)
• Update: docker compose pull && docker compose up -d

Edit compose file:

• Click the stack name
• Click “Edit” tab
• Modify YAML with syntax highlighting
• Save and restart for changes to take effect

View logs:

• Click “Logs” tab
• See real-time logs from all services
• Search logs with Ctrl+F
• Download logs for troubleshooting

Access terminal:

• Click “Terminal” tab
• Select container from dropdown
• Execute commands inside container
• Useful for debugging or maintenance tasks

---

Real-World Stack Examples

Example 1: WordPress with MySQL

A complete blog platform with database and persistent storage:

version: "3.8"

services:
  db:
    image: mysql:8.0
    container_name: wordpress-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - wordpress_net

  wordpress:
    image: wordpress:latest
    container_name: wordpress
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html
    networks:
      - wordpress_net

volumes:
  db_data:
  wp_data:

networks:
  wordpress_net:
    driver: bridge

Using environment variables:

Create .env file in /opt/stacks/wordpress/:

MYSQL_ROOT_PASSWORD=secure_root_password_here
MYSQL_PASSWORD=secure_wordpress_password_here

Dockge automatically loads .env files when deploying stacks.

Example 2: Monitoring Stack (Prometheus + Grafana)

version: "3.8"

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--storage.tsdb.retention.time=30d'

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
      - GF_INSTALL_PLUGINS=grafana-piechart-panel
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - prometheus

  node-exporter:
    image: prom/node-exporter:latest
    container_name: node-exporter
    restart: unless-stopped
    ports:
      - "9100:9100"
    command:
      - '--path.rootfs=/host'
    volumes:
      - /:/host:ro,rslave
    pid: host

volumes:
  prometheus_data:
  grafana_data:

Create prometheus.yml in stack directory:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']

  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

Example 3: Media Server (Jellyfin)

version: "3.8"

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
      - "8920:8920"  # HTTPS
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - jellyfin_config:/config
      - jellyfin_cache:/cache
      - /media/movies:/media/movies:ro
      - /media/tv:/media/tv:ro
      - /media/music:/media/music:ro
    devices:
      - /dev/dri:/dev/dri  # Hardware transcoding (Intel QuickSync)
    networks:
      - media_net

volumes:
  jellyfin_config:
  jellyfin_cache:

networks:
  media_net:
    driver: bridge

Example 4: Development Environment (PostgreSQL + Redis + pgAdmin)

version: "3.8"

services:
  postgres:
    image: postgres:16-alpine
    container_name: dev-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: developer
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: development
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - dev_net

  redis:
    image: redis:7-alpine
    container_name: dev-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
    networks:
      - dev_net

  pgadmin:
    image: dpage/pgadmin4:latest
    container_name: pgadmin
    restart: unless-stopped
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@localhost
      PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD}
    ports:
      - "5050:80"
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - dev_net

volumes:
  postgres_data:
  redis_data:
  pgadmin_data:

networks:
  dev_net:
    driver: bridge

---

Best Practices for Stack Organization

Directory Structure

Organize your stacks for maintainability:

/opt/stacks/
├── media/
│   ├── compose.yaml
│   ├── .env
│   └── config/
├── monitoring/
│   ├── compose.yaml
│   ├── prometheus.yml
│   └── grafana/
├── development/
│   ├── compose.yaml
│   └── .env
├── databases/
│   ├── compose.yaml
│   └── backups/
└── utilities/
    ├── compose.yaml
    └── data/

Naming Conventions

Stack names:

• Use lowercase with hyphens: media-server, home-automation
• Be descriptive: jellyfin-plex not media
• Group related services: monitoring-stack, arr-suite

Container names:

• Include stack context: jellyfin-media, postgres-dev
• Use consistent patterns across stacks

Environment Variables

Never hardcode secrets in compose files:

# BAD - Secret exposed
environment:
  DB_PASSWORD: "supersecret123"

# GOOD - Reference environment variable
environment:
  DB_PASSWORD: ${DB_PASSWORD}

Create .env file in each stack directory:

# .env
DB_PASSWORD=supersecret123
[email protected]
TZ=America/New_York

Important: Add .env to .gitignore if version controlling stacks.

Volume Management

Prefer named volumes over bind mounts for data:

# Better for databases and application data
volumes:
  - postgres_data:/var/lib/postgresql/data

# Better for configuration you edit
volumes:
  - ./config:/app/config

Why?

• Named volumes are managed by Docker
• Survive container deletion
• Better performance on some systems
• Portable across environments

Resource Limits

Always set resource limits for production stacks:

services:
  app:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1024M
        reservations:
          cpus: '0.5'
          memory: 512M

Prevents one service from consuming all system resources.

Health Checks

Add health checks to critical services:

services:
  web:
    image: nginx:alpine
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Enables automatic restart on failure and accurate status reporting.

---

Advanced Features and Tips

Updating Containers

Dockge makes updating containers simple:

Single stack update:

1. Click on stack
2. Click “Update” button
3. Dockge runs: docker compose pull && docker compose up -d

Manual update with specific image:

Edit compose file to pin version:

services:
  app:
    image: nginx:1.25.3  # Changed from :latest

Then click “Restart”.

Managing Multiple Compose Files

Dockge supports multiple compose files in a single stack:

/opt/stacks/complex-app/
├── compose.yaml          # Main services
├── compose.override.yaml # Local overrides
└── compose.prod.yaml     # Production settings

Docker Compose automatically merges compose.yaml and compose.override.yaml.

Agent Mode (Experimental)

Dockge can manage remote Docker hosts using agent mode:

On remote host:

docker run -d   --name dockge-agent   -v /var/run/docker.sock:/var/run/docker.sock   -v /opt/stacks:/opt/stacks   -p 5001:5001   -e DOCKGE_AGENT_MODE=true   louislam/dockge:1

On main Dockge instance: Add agent URL in settings (experimental feature, may change).

Backup Strategy

What to backup:

1. Dockge data: /opt/dockge/data
2. Stack definitions: /opt/stacks
3. Named volumes (contains actual data)

Backup script:

#!/bin/bash
# backup-dockge.sh

BACKUP_DIR="/backups/dockge"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Backup Dockge data
tar czf "$BACKUP_DIR/dockge-data-$DATE.tar.gz" /opt/dockge/data

# Backup all stacks (compose files)
tar czf "$BACKUP_DIR/stacks-$DATE.tar.gz" /opt/stacks

# Backup named volumes
docker run --rm   -v dockge_db_data:/source:ro   -v "$BACKUP_DIR":/backup   busybox tar czf /backup/volumes-$DATE.tar.gz /source

echo "Backup complete: $DATE"

Schedule with cron:

# Daily backups at 2 AM
0 2 * * * /scripts/backup-dockge.sh

Git Version Control

Track your stacks with Git:

cd /opt/stacks
git init
git add .
git commit -m "Initial stacks configuration"

# Add remote
git remote add origin https://github.com/yourusername/homelab-stacks.git
git push -u origin main

Add .gitignore:

# .gitignore
.env
*/data/
*/.env

This lets you version control compose files while excluding secrets and data.

---

Troubleshooting Common Issues

Issue: Can’t Access Dockge UI

Symptom: Browser can’t connect to http://localhost:5001

Solutions:

# Check if Dockge is running
docker ps | grep dockge

# Check logs
cd /opt/dockge
docker compose logs

# Verify port binding
sudo netstat -tlnp | grep 5001

# Firewall issue? Allow port 5001
sudo ufw allow 5001/tcp

Issue: Stack Won’t Start

Symptom: Stack shows error when clicking “Start”

Common causes:

1. Port conflict:

# Check if port is already in use
sudo netstat -tlnp | grep 8080

# Solution: Change port in compose file
ports:
  - "8081:80"  # Changed from 8080

2. Invalid YAML syntax:

# Use YAML validator
# yamllint.com

# Common mistakes:
services:
  app:
    image: nginx:latest
    ports:
      - "80:80"  # Must be quoted string or list

3. Missing environment variables:

# Check .env file exists
ls -la /opt/stacks/your-stack/.env

# Verify variables are set
cat /opt/stacks/your-stack/.env

Issue: Changes Not Reflected

Symptom: Modified compose file but container unchanged

Solution:

# Stop and remove containers
docker compose down

# Start fresh
docker compose up -d

# Or from Dockge UI:
# Click "Down" then "Start"

Issue: Permission Denied on Volumes

Symptom: Container can’t write to mounted volume

Solution:

# Check ownership
ls -la /opt/stacks/your-stack/

# Fix permissions
sudo chown -R 1000:1000 /opt/stacks/your-stack/data

# Or set user in compose file:
services:
  app:
    user: "1000:1000"

Issue: High Memory Usage

Symptom: Dockge container consuming excessive RAM

Solutions:

# Add resource limits in Dockge's own compose.yaml
services:
  dockge:
    deploy:
      resources:
        limits:
          memory: 256M

# Restart Dockge
docker compose restart

---

Security Best Practices

Network Security

Don’t expose Dockge to the internet directly:

# BAD - Accessible from internet
ports:
  - "5001:5001"

# BETTER - Localhost only
ports:
  - "127.0.0.1:5001:5001"

Safe remote access methods:

Option 1: SSH Tunnel

ssh -L 5001:localhost:5001 user@homelab-server
# Access via http://localhost:5001

Option 2: Tailscale VPN

# Install Tailscale on server
curl -fsSL https://tailscale.com/install.sh | sh

# Access via Tailscale IP
http://YOUR-TAILSCALE-IP:5001

Option 3: Reverse Proxy with Authentication

Use Nginx Proxy Manager or Caddy with HTTP basic auth.

Container Security

Run containers as non-root when possible:

services:
  app:
    user: "1000:1000"
    security_opt:
      - no-new-privileges:true

Use read-only filesystems:

services:
  app:
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

Scan images for vulnerabilities:

# Install Trivy
docker run aquasec/trivy image nginx:latest

# Check specific image
trivy image louislam/dockge:1

Secrets Management

Use Docker secrets for sensitive data:

# Create secret
echo "my_secret_password" | docker secret create db_password -

# Use in compose (Swarm mode)
services:
  db:
    secrets:
      - db_password

secrets:
  db_password:
    external: true

For non-Swarm setups, use .env files:

# Secure .env file
chmod 600 /opt/stacks/*/.env

---

Comparison with Alternatives

Dockge vs. Portainer

Use Dockge if: You only need Compose stack management Use Portainer if: You need Kubernetes, Swarm, templates, RBAC

Dockge vs. Yacht

Use Dockge if: You want active development and file-based management Use Yacht if: You prefer templates and don’t mind older software

Dockge vs. CLI (docker compose)

Use Dockge if: You want visual management Use CLI if: You’re comfortable with terminal and prefer keyboard

---

Conclusion and Next Steps

Dockge delivers on its promise: simple, elegant Docker Compose management. By focusing on doing one thing exceptionally well, it provides a refreshingly straightforward alternative to feature-bloated container management tools.

Key Takeaways

• Dockge is file-based: Your compose files remain on the filesystem, fully editable
• Simplicity is strength: No unnecessary features, just what you need
• Perfect for homelabs: Lightweight, fast, and easy to learn
• Complements other tools: Use alongside Portainer if needed
• Active development: Created by Louis Lam (Uptime Kuma author)

When to Use Dockge

Ideal scenarios:

• Managing 5-50 Docker Compose stacks on single host
• You want visual management without complexity
• You prefer editing compose files over clicking forms
• You value simplicity and speed
• You’re migrating from CLI docker compose

Not ideal for:

• Kubernetes or Swarm orchestration (use Portainer)
• Multi-user teams with RBAC needs (use Portainer BE)
• Quick deployment from templates (use Portainer)
• Managing 10+ remote Docker hosts (use Portainer)

Recommended Workflow

1. Deploy Dockge using Docker Compose method
2. Migrate existing stacks to /opt/stacks structure
3. Create new stacks through Dockge UI with syntax highlighting
4. Set up backups for both Dockge data and stack definitions
5. Optional: Version control stacks with Git
6. Optional: Run alongside Portainer for complementary features

Next Steps

Beginner:

1. Deploy Dockge following this guide
2. Create 3-5 simple stacks (nginx, database, app)
3. Practice start/stop/restart operations
4. Explore logs and terminal features

Intermediate:

1. Migrate existing compose stacks to Dockge
2. Implement proper .env file usage
3. Set up automated backups
4. Version control your stacks with Git

Advanced:

1. Experiment with agent mode for multi-host
2. Integrate with external monitoring (Uptime Kuma)
3. Create custom stack templates
4. Implement advanced security hardening

Related Guides

• Docker Basics - Foundation for container management
• Portainer Guide - Alternative comprehensive management
• Uptime Kuma - Monitor your Dockge-managed stacks
• Traefik Reverse Proxy - Secure access to services

Resources

• Official Repository: https://github.com/louislam/dockge
• Documentation: https://github.com/louislam/dockge/wiki
• Community Support: GitHub Issues and Discussions
• Creator’s Other Projects: Uptime Kuma (monitoring tool)
• Docker Compose Docs: https://docs.docker.com/compose/

---

Document Version: 1.0 Last Updated: December 16, 2024 Based on: Dockge 1.4.x Estimated Completion Time: 30 minutes (basic setup), 2-3 hours (full migration)

Happy stack managing!