Complete documentation refactoring with 57 service docs

- Refactored README.md, getting-started.md, quick-reference.md
- Enhanced setup-homelab.sh with 9-step automated process
- Created services-overview.md with all stacks
- Added comprehensive documentation for 57 services in docs/service-docs/
- All services include: overview, configuration, resources, educational content
- Coverage: Core, Infrastructure, Dashboards, Media, Media-Extended, Home Assistant, Productivity, Utilities, Monitoring, Development stacks
- Educational focus with links to tutorials, videos, and guides
This commit is contained in:
kelinfoxy
2026-01-12 18:03:12 -05:00
parent 906e6008ea
commit cba45556c7
69 changed files with 24404 additions and 1522 deletions

707
docs/service-docs/dozzle.md Normal file
View File

@@ -0,0 +1,707 @@
# Dozzle - Real-Time Docker Log Viewer
## Table of Contents
- [Overview](#overview)
- [What is Dozzle?](#what-is-dozzle)
- [Why Use Dozzle?](#why-use-dozzle)
- [How It Works](#how-it-works)
- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
- [Official Resources](#official-resources)
- [Educational Resources](#educational-resources)
- [Docker Configuration](#docker-configuration)
- [Using Dozzle](#using-dozzle)
- [Advanced Topics](#advanced-topics)
- [Troubleshooting](#troubleshooting)
## Overview
**Category:** Infrastructure Monitoring
**Docker Image:** [amir20/dozzle](https://hub.docker.com/r/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
```bash
# 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)](https://www.youtube.com/watch?v=RMm3cJSrI0s)
- [Best Docker Log Viewer? Dozzle Review](https://www.youtube.com/results?search_query=dozzle+docker+logs)
- [Docker Logging Best Practices](https://www.youtube.com/watch?v=1S3w5vERFIc)
### Articles & Guides
- [Dozzle Official Documentation](https://dozzle.dev/guide/)
- [Docker Logging Drivers](https://docs.docker.com/config/containers/logging/configure/)
- [Docker Logs Best Practices](https://docs.docker.com/config/containers/logging/)
### 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
```yaml
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):**
```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:**
```yaml
# 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:**
```yaml
dozzle:
environment:
- DOZZLE_REMOTE_HOST=tcp://remote-server:2376
# Or for agent:
- DOZZLE_AGENT_KEY=your-secret-key
```
### Custom Filters
Filter containers by labels:
```yaml
dozzle:
environment:
- DOZZLE_FILTER=status=running
- DOZZLE_FILTER=label=com.docker.compose.project=media
```
**Hide Containers:**
```yaml
mycontainer:
labels:
- "dozzle.enable=false" # Hide from Dozzle
```
### Authentication
**Built-in Simple Auth (Alternative to Authelia):**
```yaml
dozzle:
environment:
- DOZZLE_USERNAME=admin
- DOZZLE_PASSWORD=secure-password
- DOZZLE_KEY=random-32-character-key-for-cookies
```
Generate key:
```bash
openssl rand -hex 16
```
### Base Path Configuration
If running behind reverse proxy with subpath:
```yaml
dozzle:
environment:
- DOZZLE_BASE=/dozzle
```
Then access at: `https://domain.com/dozzle`
### Log Level Filtering
Show only specific log levels:
```yaml
dozzle:
environment:
- DOZZLE_LEVEL=info # Only info and above
```
Levels: `trace`, `debug`, `info`, `warn`, `error`
### Container Grouping
Group containers by label:
```yaml
# In compose file:
plex:
labels:
- "dozzle.group=media"
sonarr:
labels:
- "dozzle.group=media"
# Dozzle will group them together
```
## Troubleshooting
### Dozzle Not Showing Containers
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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):**
```yaml
services:
myapp:
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
```
**Syslog:**
```yaml
services:
myapp:
logging:
driver: syslog
options:
syslog-address: "tcp://192.168.1.1:514"
```
**Journald:**
```yaml
services:
myapp:
logging:
driver: journald
```
### Log Rotation
**Global Configuration:**
```bash
# /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:**
```yaml
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
```yaml
services:
myapp:
environment:
# Reduce log verbosity
- LOG_LEVEL=warn # Only warnings and errors
```
### Limit Containers
```yaml
dozzle:
environment:
# Only show running containers
- DOZZLE_FILTER=status=running
# Only specific projects
- DOZZLE_FILTER=label=com.docker.compose.project=media
```
### Disable Analytics
```yaml
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:
```yaml
myapp:
environment:
- FORCE_COLOR=true
- TERM=xterm-256color
```
### Regular Expressions Cheat Sheet
```regex
# 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