Dozzle in Docker: Install, Secure, and Troubleshoot

What is Dozzle? 🤔

Dozzle is a lightweight, web-based log viewer for Docker containers. Instead of running docker logs -f ... in a terminal, you get a clean UI where you can:

• 🔎 Search and filter logs
• 🧭 Switch between containers quickly
• 🟢 Watch logs live (streaming)
• 🧩 Optionally restrict which containers appear
• 🔐 Optionally enable authentication

Why it matters: When you run multiple services (Home Assistant, Jellyfin, qBittorrent, Nextcloud, etc.), logs are usually the fastest way to debug issues. Dozzle in Docker makes that workflow much easier—especially on a server like OpenMediaVault (OMV).

---

How Dozzle “connects” to your containers 🧠

Important detail: Dozzle in Docker does not connect to containers over the Docker network.

✅ Dozzle reads logs using Docker’s API. The most common method is mounting the Docker socket:

• /var/run/docker.sock

That gives Dozzle access to container metadata and logs from the same Docker host.

⚠️ Security note: mounting the Docker socket effectively gives the container high privileges (because Docker API is powerful). Use authentication, restrict exposure, or run behind a reverse proxy when appropriate.

---

Option A: Install Dozzle on the same Docker host (most common) 🏠

This is the standard approach if all containers run on the same OMV machine.

1) Create a directory for the stack 📁

sudo mkdir -p /srv/docker/dozzle
cd /srv/docker/dozzle
sudo mkdir -p data

2) Create docker-compose.yml 🧩

Example using port 8080 on the host:

services:
  dozzle:
    image: amir20/dozzle:latest
    container_name: dozzle
    restart: unless-stopped

    ports:
      - "8080:8080"

    volumes:
      # Gives Dozzle access to Docker logs on this host
      - /var/run/docker.sock:/var/run/docker.sock

      # Stores Dozzle data (e.g., users.yml when auth is enabled)
      - ./data:/data

    environment:
      DOZZLE_LEVEL: info
      # Enable auth later by uncommenting:
      # DOZZLE_AUTH_PROVIDER: simple

      # Optional: show only labeled containers
      # DOZZLE_FILTER: "label=dozzle.enabled=true"

3) Start Dozzle 🚀

sudo docker compose up -d
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' | grep -i dozzle

4) Open the UI 🌐

• http://<YOUR_OMV_IP>:8080

---

Common issue #1: “port is already allocated” 🧯

If you see an error like:

Bind for 0.0.0.0:8080 failed: port is already allocated

It means something else is already using 8080 on your host.

Find what uses 8080 🔍

sudo ss -ltnp | grep -E ':(8080)\s'
sudo docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep -E '8080->'

Fix it ✅

Option 1 (recommended): Change Dozzle host port

Edit compose:

ports:
  - "8082:8080"

Restart:

sudo docker compose down
sudo docker compose up -d

Open:

• http://<YOUR_OMV_IP>:8082

Option 2: Free port 8080

Stop the container/service already using it.

---

Optional: Show only selected containers 🎯

If you don’t want every container visible, use a label filter.

1) Enable filter in Dozzle

Uncomment in Dozzle:

environment:
  DOZZLE_FILTER: "label=dozzle.enabled=true"

2) Add labels to containers you want to show

In the compose file of any stack you want visible:

services:
  jellyfin:
    image: jellyfin/jellyfin
    labels:
      - "dozzle.enabled=true"

Restart that stack so labels are applied.

---

Optional: Enable authentication 🔐

Dozzle supports a simple auth mode using a users.yml file.

1) Generate users.yml 👤

You might try something like this:

sudo docker run -it --rm amir20/dozzle:latest generate admin \
  --password 'CHANGE_ME_STRONG' \
  --email '[email protected]' \
  --name "Admin" \
  > ./data/users.yml

But on many systems you will get:

-bash: ./data/users.yml: Permission denied

Why this happens ⚠️

Because:

• sudo applies to docker run
• but > ./data/users.yml is handled by your current shell user (e.g., pi)

So the redirect happens without root permissions.

Fix #1 (recommended): Use sudo tee ✅

cd /srv/docker/dozzle
sudo mkdir -p data

sudo docker run --rm amir20/dozzle:latest generate admin \
  --password 'CHANGE_ME_STRONG' \
  --email '[email protected]' \
  --name "Admin" \
| sudo tee ./data/users.yml >/dev/null

Fix #2: Use sudo sh -c ✅

sudo sh -c "docker run --rm amir20/dozzle:latest generate admin \
  --password 'CHANGE_ME_STRONG' \
  --email '[email protected]' \
  --name 'Admin' \
  > ./data/users.yml"

2) Enable auth in docker-compose.yml

environment:
  DOZZLE_AUTH_PROVIDER: simple

Restart:

sudo docker compose up -d
sudo docker logs --tail 200 dozzle

(Optional) Make data folder writable for your user 🧰

If you want to write files there without sudo:

sudo chown -R pi:pi /srv/docker/dozzle/data

---

Option B: View containers on multiple Docker hosts 🌍

If your containers are on different machines, the clean approach is to run Dozzle Agent on each remote host.

1) Run the agent on each host 🛰️

services:
  dozzle-agent:
    image: amir20/dozzle:latest
    container_name: dozzle-agent
    command: agent
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "7007:7007"

Start it:

sudo docker compose up -d

2) Configure the main Dozzle UI to use agents 🧭

On your main OMV host:

services:
  dozzle:
    image: amir20/dozzle:latest
    container_name: dozzle
    restart: unless-stopped
    ports:
      - "8082:8080"
    environment:
      DOZZLE_REMOTE_AGENT: "hostA:7007,hostB:7007"

⚠️ Security tip: Do not expose agent ports publicly. Restrict access (LAN/VPN/firewall).

---

Reverse Proxy (Nginx Proxy Manager) idea 🧱

If you use NPM, you can avoid publishing Dozzle directly to a host port:

• Remove ports:
• Add expose: "8080"
• Put Dozzle on the same Docker network as NPM
• Proxy a subdomain (e.g., logs.yourdomain.com)

This keeps Dozzle internal and makes TLS/SSO policies easier.

---

Quick troubleshooting checklist ✅

• 🐳 Dozzle container running?sudo docker ps | grep dozzle
• 🔌 Port conflict?sudo ss -ltnp | grep -E ':(8080|8082)\s'
• 🗂️ Auth file exists and mounted correctly?sudo ls -lah /srv/docker/dozzle/data
• 📜 Logs show errors?sudo docker logs --tail 200 dozzle

---

Summary 🧾

• Dozzle is a simple, fast way to view Docker logs in a browser 🐳📜
• On a single host, it usually works by mounting /var/run/docker.sock 🔌
• If port 8080 is busy, change the host port (e.g., 8082) 🚪
• If you enable auth, use sudo tee to avoid shell redirection permission issues 🔐
• For multiple hosts, use Dozzle Agent 🌍

Related Docker guides: Dozzle shows you what your containers are doing; the Docker security checklist for self-hosting covers how to keep them locked down, and Docker Compose vs Kubernetes helps when the stack starts to grow.