EZ-Homelab/docs/service-docs/dozzle.md

Dozzle - Real-Time Docker Log Viewer

Table of Contents

• Overview
• What is Dozzle?
• Why Use Dozzle?
• How It Works
• Configuration in AI-Homelab
• Official Resources
• Educational Resources
• Docker Configuration
• Using Dozzle
• Advanced Topics
• Troubleshooting

Overview

Category: Infrastructure Monitoring
Docker Image: amir20/dozzle
Default Stack: infrastructure.yml
Web UI: https://dozzle.${DOMAIN}
Authentication: Protected by Authelia (SSO)
Purpose: Real-time container log viewing and searching

What is Dozzle?

Dozzle is a lightweight, web-based Docker log viewer that provides real-time log streaming in a beautiful interface. It's designed to be simple, fast, and secure, requiring no database or complicated setup.

Key Features

• Real-Time Streaming: Live log updates as they happen
• Multi-Container View: View logs from multiple containers simultaneously
• Search & Filter: Search through logs with regex support
• Syntax Highlighting: Colored log output for better readability
• Dark/Light Theme: Comfortable viewing in any environment
• No Database: Reads directly from Docker socket
• Mobile Friendly: Responsive design works on phones/tablets
• Small Footprint: ~15MB Docker image
• Automatic Discovery: Finds all containers automatically
• Log Export: Download logs for offline analysis
• Authentication: Built-in auth or use reverse proxy
• Multi-Host Support: Monitor logs from multiple Docker hosts

Why Use Dozzle?

1. Quick Troubleshooting: Instantly see container errors
2. No SSH Required: Check logs from anywhere via web browser
3. Lightweight: Uses minimal resources
4. Beautiful Interface: Better than docker logs command
5. Real-Time: See logs as they happen
6. Search: Find specific errors quickly
7. Multi-Container: Monitor multiple services at once
8. Easy Access: No CLI needed for non-technical users
9. Mobile Access: Check logs from phone
10. Free & Open Source: No licensing costs

How It Works

Docker Containers → Docker Engine (logging driver)
                         ↓
                   Docker Socket (/var/run/docker.sock)
                         ↓
                    Dozzle Container
                         ↓
                    Web Interface (Real-time streaming)
                         ↓
                    Browser (You)

Log Flow

1. Containers write logs: Applications output to stdout/stderr
2. Docker captures logs: Stored by Docker logging driver
3. Dozzle reads socket: Connects to Docker socket
4. Real-time streaming: Logs pushed to browser via WebSockets
5. Display in UI: Formatted, colored, searchable logs

No Storage Required

• Dozzle doesn't store logs
• Reads directly from Docker
• Container logs stored in Docker's logging driver
• Dozzle just provides a viewing interface

Configuration in AI-Homelab

Directory Structure

# Dozzle doesn't require persistent storage
# All configuration via environment variables or command flags

Environment Variables

# No authentication (use Authelia instead)
DOZZLE_NO_ANALYTICS=true

# Hostname display
DOZZLE_HOSTNAME=homelab-server

# Base path (if behind reverse proxy)
DOZZLE_BASE=/

# Timezone
TZ=America/New_York

Official Resources

• Website: https://dozzle.dev
• GitHub: https://github.com/amir20/dozzle
• Docker Hub: https://hub.docker.com/r/amir20/dozzle
• Documentation: https://dozzle.dev/guide/
• Live Demo: https://dozzle.dev/demo

Educational Resources

Videos

• Dozzle - Docker Log Viewer (Techno Tim)
• Best Docker Log Viewer? Dozzle Review
• Docker Logging Best Practices

Articles & Guides

• Dozzle Official Documentation
• Docker Logging Drivers
• Docker Logs Best Practices

Concepts to Learn

• Container Logs: stdout/stderr output from containers
• Docker Logging Drivers: json-file, syslog, journald, etc.
• Log Rotation: Managing log file sizes
• WebSockets: Real-time browser communication
• Docker Socket: Unix socket for Docker API
• Log Levels: DEBUG, INFO, WARN, ERROR
• Regex: Pattern matching for log searching

Docker Configuration

Complete Service Definition

dozzle:
  image: amir20/dozzle:latest
  container_name: dozzle
  restart: unless-stopped
  networks:
    - traefik-network
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  environment:
    - DOZZLE_NO_ANALYTICS=true
    - DOZZLE_HOSTNAME=homelab-server
    - TZ=America/New_York
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.dozzle.rule=Host(`dozzle.${DOMAIN}`)"
    - "traefik.http.routers.dozzle.entrypoints=websecure"
    - "traefik.http.routers.dozzle.tls.certresolver=letsencrypt"
    - "traefik.http.routers.dozzle.middlewares=authelia@docker"
    - "traefik.http.services.dozzle.loadbalancer.server.port=8080"

Important Notes

1. Docker Socket: Read-only access sufficient
2. Port 8080: Default Dozzle web interface port
3. No Ports Exposed: Access only via Traefik
4. Authelia Required: No built-in auth, use Authelia

Using Dozzle

Interface Overview

Main Screen:

• List of all containers
• Status (running/stopped)
• Container names
• Click to view logs

Container View:

• Real-time log streaming
• Search box at top
• Timestamp toggle
• Download button
• Container stats
• Multi-container tabs

Viewing Logs

Single Container:

1. Click container name
2. Logs stream in real-time
3. Auto-scrolls to bottom
4. Click timestamp to stop auto-scroll

Multiple Containers:

1. Click first container
2. Click "+" button
3. Select additional containers
4. View logs side-by-side or merged

Searching Logs

Basic Search:

1. Type in search box
2. Press Enter
3. Matching lines highlighted
4. Navigate with arrow buttons

Advanced Search (Regex):

# Find errors
error|fail|exception

# Find specific IP
192\.168\.1\..*

# Find HTTP codes
HTTP/[0-9]\.[0-9]" [45][0-9]{2}

# Case insensitive
(?i)warning

Filtering Options

Filter by:

• Container name
• Log content
• Time range (scroll to older logs)
• Log level (if structured logs)

Log Export

Download Logs:

1. View container logs
2. Click download icon
3. Choose time range
4. Save as text file

Interface Features

Toolbar:

• 🔍 Search box
• ⏸️ Pause auto-scroll
• ⬇️ Download logs
• 🕐 Toggle timestamps
• ⚙️ Settings
• 🌙 Dark/Light mode toggle

Keyboard Shortcuts:

• / - Focus search
• Esc - Clear search
• Space - Pause/Resume scroll
• g - Scroll to top
• G - Scroll to bottom

Advanced Topics

Multi-Host Monitoring

Monitor Docker on multiple servers:

Remote Host Requirements:

# On remote server - expose Docker socket via TCP (secure)
# Or use Dozzle agent

# Agent on remote server:
dozzle-agent:
  image: amir20/dozzle:latest
  command: agent
  environment:
    - DOZZLE_AGENT_KEY=your-secret-key
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro

Main Dozzle:

dozzle:
  environment:
    - DOZZLE_REMOTE_HOST=tcp://remote-server:2376
    # Or for agent:
    - DOZZLE_AGENT_KEY=your-secret-key

Custom Filters

Filter containers by labels:

dozzle:
  environment:
    - DOZZLE_FILTER=status=running
    - DOZZLE_FILTER=label=com.docker.compose.project=media

Hide Containers:

mycontainer:
  labels:
    - "dozzle.enable=false"  # Hide from Dozzle

Authentication

Built-in Simple Auth (Alternative to Authelia):

dozzle:
  environment:
    - DOZZLE_USERNAME=admin
    - DOZZLE_PASSWORD=secure-password
    - DOZZLE_KEY=random-32-character-key-for-cookies

Generate key:

openssl rand -hex 16

Base Path Configuration

If running behind reverse proxy with subpath:

dozzle:
  environment:
    - DOZZLE_BASE=/dozzle

Then access at: https://domain.com/dozzle

Log Level Filtering

Show only specific log levels:

dozzle:
  environment:
    - DOZZLE_LEVEL=info  # Only info and above

Levels: trace, debug, info, warn, error

Container Grouping

Group containers by label:

# In compose file:
plex:
  labels:
    - "dozzle.group=media"

sonarr:
  labels:
    - "dozzle.group=media"

# Dozzle will group them together

Troubleshooting

Dozzle Not Showing Containers

# Check if Dozzle can access Docker socket
docker exec dozzle ls -la /var/run/docker.sock

# Verify containers are running
docker ps

# Check Dozzle logs
docker logs dozzle

# Test socket access
docker exec dozzle docker ps

Logs Not Updating

# Check container is producing logs
docker logs container-name

# Verify WebSocket connection
# Open browser console: F12 → Network → WS
# Should see WebSocket connection

# Check browser console for errors
# F12 → Console

# Try different browser
# Some corporate firewalls block WebSockets

Can't Access Web Interface

# Check if Dozzle is running
docker ps | grep dozzle

# Check Traefik routing
docker logs traefik | grep dozzle

# Test direct access (if port exposed)
curl http://localhost:8080

# Check network connectivity
docker exec dozzle ping traefik

Search Not Working

# Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

# Check search syntax
# Use proper regex escaping

# Try simple text search first
# Then progress to regex

# Check browser console for JavaScript errors

High Memory Usage

# Check Dozzle stats
docker stats dozzle

# Viewing many containers at once increases memory
# Close unnecessary container tabs

# Restart Dozzle
docker restart dozzle

# Limit containers with filters
DOZZLE_FILTER=status=running

Logs Cut Off / Incomplete

# Docker has log size limits
# Check logging driver config

# View Docker daemon log config
docker info | grep -A5 "Logging Driver"

# Configure log rotation (in daemon.json):
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Docker Logging Configuration

Logging Drivers

JSON File (Default):

services:
  myapp:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Syslog:

services:
  myapp:
    logging:
      driver: syslog
      options:
        syslog-address: "tcp://192.168.1.1:514"

Journald:

services:
  myapp:
    logging:
      driver: journald

Log Rotation

Global Configuration:

# /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "compress": "true"
  }
}

# Restart Docker
sudo systemctl restart docker

Per-Container:

services:
  myapp:
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"

Best Practices

1. Set Max Size: Prevent disk space issues
2. Rotate Logs: Keep 3-5 recent files
3. Compress Old Logs: Save disk space
4. Structured Logging: JSON format for better parsing
5. Log Levels: Use appropriate levels (debug, info, error)
6. Sensitive Data: Never log passwords or secrets

Performance Optimization

Reduce Log Volume

services:
  myapp:
    environment:
      # Reduce log verbosity
      - LOG_LEVEL=warn  # Only warnings and errors

Limit Containers

dozzle:
  environment:
    # Only show running containers
    - DOZZLE_FILTER=status=running
    
    # Only specific projects
    - DOZZLE_FILTER=label=com.docker.compose.project=media

Disable Analytics

dozzle:
  environment:
    - DOZZLE_NO_ANALYTICS=true

Security Considerations

1. Protect with Authelia: Never expose Dozzle publicly without auth
2. Read-Only Socket: Use :ro for Docker socket mount
3. Use Docker Proxy: Consider Docker Socket Proxy for extra security
4. Network Isolation: Keep on trusted network
5. Log Sanitization: Ensure logs don't contain secrets
6. HTTPS Only: Always use SSL/TLS
7. Limited Access: Only give access to trusted users
8. Monitor Access: Review who accesses logs
9. Log Retention: Don't keep logs longer than necessary
10. Regular Updates: Keep Dozzle updated

Comparison with Alternatives

Dozzle vs Portainer Logs

Dozzle:

• Specialized for logs
• Real-time streaming
• Better search/filter
• Lighter weight
• Multiple containers simultaneously

Portainer:

• Full Docker management
• Logs + container control
• More features
• Heavier resource usage

Dozzle vs CLI (docker logs)

Dozzle:

• Web interface
• Multi-container view
• Search functionality
• No SSH needed
• User-friendly

CLI:

• Scriptable
• More control
• No additional resources
• Faster for experts

Dozzle vs Loki/Grafana

Dozzle:

• Simple setup
• No database
• Real-time only
• Lightweight

Loki/Grafana:

• Log aggregation
• Long-term storage
• Advanced querying
• Complex setup
• Enterprise features

Tips & Tricks

Quick Container Access

Bookmark Specific Containers:

https://dozzle.yourdomain.com/show?name=plex
https://dozzle.yourdomain.com/show?name=sonarr

Multi-Container Monitoring

Monitor entire stack:

https://dozzle.yourdomain.com/show?name=plex&name=sonarr&name=radarr

Color-Coded Logs

If your app supports colored output:

myapp:
  environment:
    - FORCE_COLOR=true
    - TERM=xterm-256color

Regular Expressions Cheat Sheet

# Find errors
error|exception|fail

# Find warnings
warn|warning|caution

# Find IP addresses
\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}

# Find URLs
https?://[^\s]+

# Find timestamps
\d{4}-\d{2}-\d{2}

# Case insensitive
(?i)search_term

Summary

Dozzle is a simple, lightweight tool for viewing Docker container logs. It provides:

• Beautiful web interface for log viewing
• Real-time log streaming
• Multi-container support
• Search and filter capabilities
• No database or complex setup required
• Minimal resource usage

Perfect for:

• Quick troubleshooting
• Development environments
• Non-technical user access
• Mobile log viewing
• Real-time monitoring

Not ideal for:

• Long-term log storage
• Advanced log analysis
• Log aggregation across many hosts
• Compliance/audit requirements

Remember:

• Protect with Authelia
• Use read-only Docker socket
• Configure log rotation
• Monitor disk space
• Logs are ephemeral (not stored by Dozzle)
• Great complement to Grafana/Loki for detailed analysis