How to Use Dozzle: The Beginner's Guide (First Run, the Sock Lesson, the Interface Tour, and the Log-Rotation Rule)

CodexFuse Team · 2026-11-01T02:03:08.427Z · 12 min read

Learn how to use Dozzle: run the real-time Docker log viewer, master the docker.sock security lesson, tour the interface, search across containers, add auth, and set log rotation.

If you run a handful of Docker containers, you know the debugging loop: SSH in, run docker logs -f on one container, stop it, repeat for the next one. Learning how to use Dozzle replaces that loop with a browser tab. Dozzle is a free, open-source, real-time Docker log viewer: one tiny container that mounts the Docker socket and streams every container's logs to a live web interface — searchable, filterable, and watchable side by side. This is the dozzle tutorial for beginners: your first run, the docker.sock security lesson everyone skips, a tour of the interface, searching and filtering across containers, monitoring a remote host with the Dozzle agent, adding authentication, putting Dozzle behind a reverse proxy, and the log-rotation rule that keeps your disk from filling up. New to containers entirely? Start with our Docker beginner guide — Dozzle only makes sense once Docker itself feels familiar.

What Is Dozzle?

Dozzle is a lightweight, real-time Docker log viewer that runs as a single container and shows you the logs of every container on the host in your browser. Instead of SSH sessions and terminal tails, you open a web page, click a container, and watch its log lines stream in live. The project behind it is amir20/dozzle on GitHub — MIT-licensed, with roughly 14,772 stars, created in October 2018, and still actively pushed (the latest release, v11.4.0, landed October 30, 2026; homepage dozzle.dev). It has no database and no backend state: it simply reads the Docker Engine API through the mounted socket and renders what the daemon already knows.

That design is the whole point. Dozzle is a viewer, not a log-management platform. It does not collect, index, or archive logs — it shows you what the Docker daemon is holding right now, beautifully. If you need indexed search over months of history, you want a log-search lane tool like Quickwit; if you need to watch what is happening right now, you want Dozzle.

What Do You Need Before You Install Dozzle?

You need three things: a machine with Docker running at least one container, the Docker socket at /var/run/docker.sock, and a browser. That is the whole prerequisite list — Dozzle's image is small and its resource footprint is near zero when idle. Most self-hosters run it on the same VPS that hosts their apps; if you have not picked a server yet, our what is VPS hosting guide explains what to look for. You will also want port 8080 free on the host, or you can map a different host port to Dozzle's internal 8080.

One more thing to decide before the first run: whether this box is a machine you trust. The next two sections explain why that question matters more than any config flag.

How Do You Run Dozzle for the First Time?

The fastest way to learn how to use Dozzle is the ten-step first-run arc below — docker run first, compose after. Follow it on your Docker host and you will be watching live logs in under two minutes.

1. SSH into your Docker host — the machine whose containers you want to watch.
2. Pull the current image. docker pull amir20/dozzle:latest — the :latest tag tracks the current release line (v11.4.0 as of October 30, 2026), and the Hub carries thousands of versioned tags if you ever want to pin one.
3. Run it with the socket mounted. The socket mount is the entire installation:

   docker run --name dozzle -d --restart unless-stopped \
     -p 8080:8080 \
     -v /var/run/docker.sock:/var/run/docker.sock:ro \
     amir20/dozzle:latest

4. Open the interface. Visit http://YOUR-HOST-IP:8080 — Dozzle listens on 8080 inside the container and the -p flag publishes it.
5. Check the health endpoint. http://YOUR-HOST-IP:8080/health should answer — it is the same check your reverse proxy and uptime monitors will use later.
6. Click a container in the table. Every container on the host appears with its name, image, and state; click one and its log stream starts flowing in real time.
7. Search the stream. Type a keyword into the search box and the stream filters to matching lines — the fastest way to find an error in a noisy log.
8. Open a second container beside the first. Split the screen and watch two streams at once — this is how you correlate an app error with its database's log.
9. Star a favorite. Pin the containers you check daily so they sit at the top of the table.
10. Compose-ify it. Move the one-off command into a compose file so it survives reboots and host moves:

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

    You can generate the surrounding stack boilerplate with our Docker Compose generator and drop this service in.

The Docker Sock Lesson: Why the Socket Mount Is Root-Equivalent Power

Here is the lesson every beginner guide should lead with: mounting /var/run/docker.sock gives Dozzle — and anyone who can reach Dozzle — the power to start, stop, delete, and create containers on the host. The Docker daemon runs as root, and the socket is its front door. A container holding the socket can launch a new privileged container and escape to the host. Treat Dozzle's port the way you would treat an SSH port.

Two details beginners get wrong. First, the :ro flag does not restrict what Dozzle can do through the API — it only mounts the socket file read-only on the filesystem; API calls flow exactly the same. Second, the beginner arc above publishes 8080 only because you are testing on a trusted network. The rules from here on are simple: never publish Dozzle's port to the public internet without authentication in front of it, add a password before you go further (next section but one), and if you want defense in depth, put a Docker socket proxy between Dozzle and the daemon so only the API calls a log viewer actually needs are allowed through.

Dozzle Interface Tour: the Container Table, the Live Stream, Search, and Favorites

The interface is four ideas, and you will learn all of them in one sitting. The container table is the home screen: every container on the host, with name, image, and state, so you can see at a glance what is running and what just crashed. Click any row and the live stream opens — a real-time tail of that container's logs, auto-scrolling as new lines arrive, with a pause button for when you need to read a stack trace without it running away. The search box filters the stream to the lines you care about, and favorites pin your daily-driver containers to the top so you never hunt for them again.

The feature that makes Dozzle worth the install is the multi-container view: split the screen and stream several containers at once. The classic beginner workflow is your app container on the left and its database on the right — when the app throws an error, you see the database's complaint in the same glance, no tab-switching, no second SSH session. For a dozzle for beginners milestone, this is the one to practice: single-container tailing is what you already had; correlated multi-stream watching is what Dozzle adds.

How Do You Search and Filter Logs Across Containers?

Type into the search box to filter the open stream to matching lines, and open the multi-container view to run that search across several containers at once. Dozzle's search is a filter on the lines the daemon is streaming — instant, but it works on what is currently visible in the buffer, not on a historical index.

Two practical patterns cover most debugging. The error hunt: open the misbehaving container, search for "error" or "exception", and scroll the filtered lines. The correlation sweep: split the screen across the app, the database, and the reverse proxy, search the same term in each, and line up the timestamps. If you find yourself needing to search logs from last week rather than right now, you have outgrown a viewer and need indexed log storage — the rotation rule below will also start mattering to you.

How Do You Monitor a Remote Host with Dozzle?

Run the Dozzle agent on each remote host and connect your main Dozzle to it — logs from every host land in one interface. The agent is the same image started in agent mode (dozzle agent), which listens on port 7007 with TLS and mounts the remote host's docker.sock. Your main Dozzle container is told about each agent, and the container table grows a per-host view: one tab, many machines, still no SSH.

This is the dozzle remote host workflow that homelabbers graduate to: one main instance on the primary box, agents on the Pi, the NAS, the VPS. Keep agent traffic on trusted networks or a VPN, because the agents carry the same socket power as the main instance. If you run Docker Swarm instead of standalone hosts, there is a simpler path: set DOZZLE_MODE=swarm and Dozzle talks to the Swarm directly with no agents needed.

How Do You Add Authentication to Dozzle?

Set DOZZLE_AUTH_PROVIDER=simple and mount a users.yml file — then Dozzle asks for a username and password before showing a single log line. Generate the users file with the image's built-in generator (dozzle generate, per the current docs), mount it into the container, and restart. That one change turns the sock lesson from scary to managed: even if someone reaches the port, they still cannot see your containers.

A stale-guide warning: the old DOZZLE_USER / DOZZLE_PASS variables are gone from the current documentation — guides that reference them predate the users.yml era, so do not be confused when those variables do nothing on v11. Teams that outgrow passwords have two more providers in the current docs: forward-proxy authentication (let your reverse proxy or identity provider handle who is who) and OIDC for proper single sign-on.

How Do You Put Dozzle Behind a Reverse Proxy?

Keep Dozzle on its internal port and proxy 443 down to 8080 with your web server, adding TLS — the /health endpoint gives the proxy a real upstream check. The rule is absolute for anything internet-facing: no direct 8080, no exceptions, and authentication stays on even behind the proxy.

The standard nginx pattern is a location block that passes traffic to the local Dozzle port with websocket upgrade headers, plus a TLS certificate (the certbot flow covers the certificate part in minutes). Behind the proxy, your uptime monitor can poll /health and your logs stay reachable at https://logs.yourdomain.com instead of a bare IP and port. This is also the moment to stop publishing 8080 on the host at all — bind the port mapping to localhost in your compose file once the proxy is in place.

The Log-Rotation Rule: Why json-file Logs Never Shrink

Here is the rule that saves disks: Docker's default json-file logging driver keeps every log line forever — max-size defaults to -1, meaning unlimited — so one chatty container can silently fill your entire disk while you are admiring how pretty its logs look in Dozzle. The fix is a few lines in the daemon config:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "compress": "true"
  }
}

That caps each container at three 10 MB files with compression — 30 MB per container, forever, instead of infinity. Two caveats that bite beginners. First, the daemon config applies to new containers only: containers you already created keep their old unlimited settings until you recreate them, so run this on a fresh host or plan a recreate pass. Second, Dozzle shows you the logs; it does not manage them — rotation is the daemon's job, and this config is how you hand it the job. While you are hardening the host, automate the other half of maintenance too: our Watchtower beginner guide keeps your containers' images updated without the Sunday-night ritual.

Dozzle vs docker logs vs Portainer: Which Should You Use?

Pick the tool that matches the job — they are siblings, not rivals. This is the original comparison the lane needed:

Dozzle wins the pure viewing job because it is the only one built for it: multi-stream correlation, per-container search, and a zero-config UI that a teammate can use without SSH access. Portainer wins the management job — if you spend your days starting and stopping containers, read our Portainer beginner guide and keep Dozzle beside it for the logs. And docker logs -f never goes away: it is still the fastest answer when you are already in the terminal.

Sources

Every fact in this guide was verified against a live source on 2026-11-01: GitHub API — amir20/dozzle repository (star count, MIT license, creation and push dates); GitHub API — amir20/dozzle releases (v11.4.0 release date); Docker Hub — amir20/dozzle tags (the :latest tag and internal port 8080); dozzle.dev official documentation (authentication providers, agent mode on port 7007, DOZZLE_MODE=swarm, the /health endpoint); Docker official documentation — configure logging drivers (json-file max-size / max-file defaults and daemon.json keys).

Frequently Asked Questions

Is Dozzle free?

Yes. Dozzle is MIT-licensed open source that you self-host, so there is no subscription and no per-seat pricing — the only cost is the machine it runs on, which for most self-hosters is a VPS they already pay for.

Is mounting docker.sock safe?

It is safe the way a front door is safe: it is the correct design, but you must lock it. The socket gives root-equivalent power, the :ro flag does not reduce that power, so always add authentication, never publish the port to the public internet without a reverse proxy and TLS, and consider a socket proxy for defense in depth.

Can Dozzle show logs from a remote server?

Yes — run the Dozzle agent on each remote host (dozzle agent, TLS on port 7007) and connect your main Dozzle to it. All hosts' containers appear in one interface. For Docker Swarm, DOZZLE_MODE=swarm replaces the agents entirely.

Why are my old logs missing in Dozzle?

Dozzle streams what the Docker daemon currently holds; it does not keep its own archive. If a container was recreated, its old log file went with it, and if the daemon's json-file logs rotated, the oldest lines are gone by design. Set the rotation rule from this guide so you control how much history survives.

Does Dozzle replace Portainer?

No. Dozzle is a log viewer; Portainer is a container manager. They overlap nowhere that matters: use Dozzle for watching and searching logs, Portainer for deploying and managing containers — many self-hosters run both.