homelab/compose/services/dozzle/README.md

# Dozzle - Simple Docker Log Viewer

A lightweight, web-based Docker log viewer with real-time streaming.

## Features

- ✅ **Real-time log streaming** - See logs as they happen
- ✅ **Search and filter** - Find specific log entries instantly
- ✅ **Multi-container view** - View multiple containers side-by-side
- ✅ **No database required** - Reads directly from Docker
- ✅ **Tiny footprint** - Only ~4MB image size
- ✅ **Container stats** - CPU, memory usage per container
- ✅ **Dark/Light themes** - Easy on the eyes

## Access

**URL:** https://logs-docker.fig.systems

## Quick Start

### Deploy

```bash
cd /home/eduardo_figueroa/homelab/compose/services/dozzle
docker compose up -d
```

### View Logs

1. Open https://logs-docker.fig.systems
2. Click on any container to view logs
3. Use search box to filter logs
4. Click "Settings" to change theme, tail size, etc.

## Features Guide

### Real-Time Streaming

- Logs update automatically as new entries arrive
- Pause/resume streaming with the pause button
- Auto-scrolls to latest logs (disable to scroll through history)

### Search & Filter

**Search box features:**
- Simple text search: `error`
- Case-sensitive toggle
- Regex support: `HTTP [45]\d{2}`
- Multi-word: `error database connection`

**Quick filters:**
- Click container name to filter to that container
- Use dropdown to switch between containers
- Multi-container view: Click "+" to add more containers

### Container Stats

Click "Stats" tab to view:
- CPU usage %
- Memory usage (MB)
- Network I/O
- Block I/O

### Multi-Container View

View logs from multiple containers simultaneously:
1. Click container to open logs
2. Click "+" button in header
3. Select another container
4. View side-by-side or stacked

### Download Logs

- Click "Download" button (top right)
- Downloads current view as .txt file
- Includes visible log lines only

### Settings

Click gear icon to configure:
- **Theme**: Dark or light mode
- **Tail size**: Number of lines to load (default: 300)
- **Datetime format**: Customize timestamp display
- **Font size**: Adjust log text size

## Log Retention

**Note:** Dozzle shows logs from Docker's log driver. By default, Docker keeps logs indefinitely, which can consume disk space.

### Check Current Log Size

```bash
# See total size of all container logs
sudo du -sh /var/lib/docker/containers/

# Size per container
sudo du -sh /var/lib/docker/containers/*
```

### Configure Log Rotation (Recommended)

Create/edit `/etc/docker/daemon.json`:

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

This keeps:
- Max 10MB per log file
- Max 3 files per container
- ~30MB total per container

Then restart Docker:
```bash
sudo systemctl restart docker
```

**Note:** Existing containers need to be recreated to use new settings.

## Limitations

### Log History

Dozzle shows what Docker has stored. To view logs from the last week:

1. **Ensure Docker is keeping enough logs** (see log rotation above)
2. **Increase tail size** in Dozzle settings (default: 300 lines)
3. **Scroll up** in log view to see older entries

If you need longer-term log storage and analysis, continue using Loki/Grafana for historical queries.

### vs Loki/Grafana

**Use Dozzle for:**
- Quick log checks
- Real-time monitoring
- Simple searching
- Single-server setups

**Use Loki/Grafana for:**
- Long-term log retention
- Complex queries across time ranges
- Multi-server log aggregation
- Alerts based on log patterns
- Historical analysis

## Authentication

To enable basic auth (recommended for external access):

1. Edit `.env`:
   ```bash
   DOZZLE_USERNAME=admin
   DOZZLE_PASSWORD=your-secure-password
   ```

2. Uncomment auth lines in `compose.yaml`:
   ```yaml
   environment:
     DOZZLE_USERNAME: ${DOZZLE_USERNAME}
     DOZZLE_PASSWORD: ${DOZZLE_PASSWORD}
   ```

3. Restart:
   ```bash
   docker compose up -d
   ```

## Multi-Host Setup

To view logs from multiple Docker hosts:

1. Configure remote Docker hosts to expose API (carefully!)
2. Add to compose.yaml:
   ```yaml
   environment:
     DOZZLE_REMOTE_HOST: tcp://remote-host:2375|Remote Server Name
   ```

Or add via UI: Settings → Hosts → Add host

## Troubleshooting

### No containers showing

**Check Docker socket access:**
```bash
docker logs dozzle
```

Should see: "Dozzle version X.X.X"

### Slow performance

**Reduce tail size:** Settings → Tail size → 100

### Old logs not showing

**Check Docker log retention:**
```bash
docker inspect <container> | grep -A 10 "LogConfig"
```

If `max-size` is too small, increase it in `/etc/docker/daemon.json`

## Keyboard Shortcuts

- `/` - Focus search box
- `Esc` - Clear search
- `Space` - Pause/resume streaming
- `↑/↓` - Scroll logs
- `Ctrl+F` - Browser find

## Tips

1. **Bookmark frequently-checked containers** - Use browser bookmarks for direct URLs
2. **Use browser tabs** - Open multiple containers in separate tabs
3. **Combine with Loki** - Use Dozzle for live monitoring, Loki for historical queries
4. **Set up log rotation** - Prevent disk space issues
5. **Enable auth** - If exposed to internet

## Links

- **Documentation:** https://dozzle.dev/
- **GitHub:** https://github.com/amir20/dozzle
- **Docker Hub:** https://hub.docker.com/r/amir20/dozzle