homelab/dozzle
1
0
Fork 0
mirror of https://github.com/amir20/dozzle.git synced 2026-08-07 10:14:44 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

chore: expand and tighten guide docs

Browse Source 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Amir Raminfar
2026-04-23 12:42:49 -07:00
parent 6ce3750062
commit 116006dbbf
9 changed files with 131 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/actions.md
+4 -1
View File
@@ -8,7 +8,10 @@ title: Container Actions
Dozzle supports container actions, which allows you to `start`, `stop`, `restart`, `remove`, and `update` containers from the dropdown menu on the right next to the container stats. This feature is **disabled** by default and can be enabled by setting the environment variable `DOZZLE_ENABLE_ACTIONS` to `true`.
The `update` action pulls the latest image for the container and recreates it with the same configuration — useful for upgrading a container in place without editing its compose file.
The `update` action pulls the latest image for the container and recreates it with the same configuration — useful for upgrading a container in place without editing its compose file. `update` only has a meaningful effect when the image uses a moving tag (e.g. `latest`, `stable`); a pinned tag will simply re-pull the same image.
> [!WARNING]
> `remove` and `update` recreate the container. Data written to **anonymous volumes** or the container's writable layer will be lost. Named volumes and bind mounts are preserved.
> [!NOTE]
> Enabling actions also unlocks Compose [Deployments](/guide/deployments) when using [Dozzle Cloud](/guide/dozzle-cloud).
docs/guide/analytics.md
+17 -3
View File
@@ -4,12 +4,26 @@ title: Anonymous Analytics
# Data Collection of Analytics
Dozzle collects anonymous user configurations using a simple beacon written in Go. _Why?_ Dozzle is an open source project with no funding. As a result, there is no time to do user studies of Dozzle. Analytics are collected to prioritize features and fixes based on how people use Dozzle.
Dozzle collects anonymous usage data via a lightweight beacon to help prioritize features and fixes. It is an open-source project with no funding, so this data is the primary signal for where to invest effort.
## What is Collected
At a high level, the beacon includes things like the Dozzle version, deployment mode (server, swarm, k8s, agent), which auth provider is enabled, a few feature flags, the Docker Engine version, and small counts (number of hosts, containers, filters). A random per-install ID is included for deduplication.
No log contents, container names, image names, IP addresses, or user identifiers are ever transmitted. The exact set of fields evolves over time — the authoritative source is [`types/beacon.go`](https://github.com/amir20/dozzle/blob/master/types/beacon.go), and the sender is [`internal/analytics/http_beacon.go`](https://github.com/amir20/dozzle/blob/master/internal/analytics/http_beacon.go).
## Where is Data Stored
Dozzle sends anonymous data to DigitalOcean, where it is written to a flat file for processing.
Events are posted to `https://b.dozzle.dev/event`, a small Go service that writes events to a flat file on DigitalOcean for later processing.
## Opting Out
Dozzle analytics helps to prioritize features and spend time on the most important improvements. If you do not want to be tracked, use the `--no-analytics` flag or `DOZZLE_NO_ANALYTICS` environment variable.
Pass `--no-analytics` or set `DOZZLE_NO_ANALYTICS=true`. No beacon requests will be made.
```yaml
services:
dozzle:
image: amir20/dozzle:latest
environment:
DOZZLE_NO_ANALYTICS: "true"
```
docs/guide/debugging.md
+21 -1
View File
@@ -4,7 +4,15 @@ title: Debugging
# Debugging with Logs
By default, Dozzle does not output a lot of logs. However, this can be changed with the `--level` flag. The default value is `info` which only prints limited logs. You can use `debug` or `trace` which will show details about memory, configuration and other stats. `DOZZLE_LEVEL` can be used in compose configurations. Below is an example of using `docker-compose.yml` file to enable `debug` level.
By default Dozzle logs at `info` level, which is intentionally quiet. When something isn't working, turn up the verbosity using the `--level` flag or the `DOZZLE_LEVEL` environment variable.
| Level | When to use |
| ------- | ---------------------------------------------------------------------------- |
| `info` | Default. Startup details, errors, and warnings. |
| `debug` | Request-level diagnostics, auth decisions, agent connections, config dump. |
| `trace` | Everything. Individual log events, beacon payloads, gRPC frames. Very noisy. |
Dozzle writes all logs to `stdout`, so `docker logs dozzle` is the right place to read them.
```yaml
services:
@@ -17,3 +25,15 @@ services:
environment:
DOZZLE_LEVEL: debug
```
## Reporting a Bug
If you think you've hit a bug, please open an issue at [github.com/amir20/dozzle/issues](https://github.com/amir20/dozzle/issues). Include:
- Dozzle version (visible in the UI footer or `dozzle --version`)
- Deployment mode: server, swarm, k8s, or agent
- Docker or Kubernetes version
- Relevant `debug`- or `trace`-level log output
- Steps to reproduce, ideally with a minimal `docker-compose.yml`
The more context in the initial report, the faster it can be triaged.
docs/guide/dtop.md
+12 -2
View File
@@ -4,18 +4,28 @@ title: Introducing dtop
# What is dtop?
`dtop` is a command-line tool that provides a real-time view of the Docker containers running on your system. It is a lightweight alternative to the `docker ps` command, and it is designed to be used in a terminal or command prompt. `dtop` supports connecting to multiple hosts via `ssh`, `tcp` or `unix socket`. It also integrates with Dozzle by providing a quick way to open logs quickly.
`dtop` is a command-line companion to Dozzle that provides a real-time terminal view of the Docker containers running on your system. Think of it as a richer `docker ps` you can leave open in a tmux pane — and when you need the full log history, search, or charts, `dtop` lets you jump straight into Dozzle.
It connects to Docker hosts via `ssh`, `tcp`, or a local `unix socket`, making it well suited for the same multi-host setups Dozzle supports.
![dtop screenshot](https://github.com/amir20/dtop/raw/master/demo.gif)
## Installation
Full installation instructions can be found at [https://github.com/amir20/dtop](https://github.com/amir20/dtop?tab=readme-ov-file#installation). You can use Docker to quickly run `dtop`:
Install with Homebrew:
```bash
brew install dtop
```
Or run it via Docker without installing anything:
```bash
docker run -v /var/run/docker.sock:/var/run/docker.sock -it ghcr.io/amir20/dtop:latest
```
Full installation instructions can be found at [https://github.com/amir20/dtop](https://github.com/amir20/dtop?tab=readme-ov-file#installation).
## Project Status
`dtop` is a new project and not feature rich as Dozzle. However, I am actively working on adding more features. I use it personally to monitor all my containers across multiple hosts on the command line. If you have suggestions then please open issues at [https://github.com/amir20/dtop/issues](https://github.com/amir20/dtop/issues).
docs/guide/getting-started.md
+9
View File
@@ -38,6 +38,15 @@ services:
#
# Uncomment to enable authentication. See https://dozzle.dev/guide/authentication
# - DOZZLE_AUTH_PROVIDER=simple
#
# Label this Dozzle instance (shown in the header and multi-host menu). See https://dozzle.dev/guide/hostname
# - DOZZLE_HOSTNAME=my-server
#
# Connect to one or more remote agents to monitor other Docker hosts. See https://dozzle.dev/guide/agent
# - DOZZLE_REMOTE_AGENT=192.168.1.10:7007,192.168.1.11:7007
#
# Only show containers matching a filter. See https://dozzle.dev/guide/filters
# - DOZZLE_FILTER=label=com.example.app
volumes:
dozzle_data:
```
docs/guide/healthcheck.md
+17 -3
View File
@@ -4,7 +4,7 @@ title: Healthcheck
# Enabling Healthcheck
Dozzle has internal support for healthcheck using the `dozzle healthcheck` command. It is not enabled by default as it adds extra CPU usage. To use `healthcheck`, you need to configure it. Below is an example that checks the health of Dozzle every 3 seconds.
Dozzle ships a built-in `dozzle healthcheck` subcommand. It is not wired into the image by default because it adds a small amount of CPU overhead. Enable it from your compose file:
```yaml
services:
@@ -22,7 +22,21 @@ services:
start_period: 30s
```
`dozzle healthcheck` skips agents as they are not required for healthcheck. Agents can be configured to have their own [healthcheck](/guide/agent#setting-up-healthcheck).
## What It Checks
When running as a server, `dozzle healthcheck` sends an HTTP `GET` to its own `/healthcheck` endpoint. The endpoint pings every **local** Docker client (up to 3s per client) and returns:
- `200 OK` — at least one local Docker client responded, **or** no local clients are configured but at least one remote agent host is known.
- `500 Internal Server Error` — all local clients failed to ping and no agent hosts are known.
Remote agents are intentionally **not** part of the server's healthcheck — an unreachable agent should not mark the main Dozzle process unhealthy. Each agent can expose its own healthcheck; see [Agent healthcheck](/guide/agent#setting-up-healthcheck).
## Exit Codes
- `0` — healthy (HTTP 200)
- non-zero — unhealthy, network error, or non-200 response. The failing URL and status are logged to stdout.
The command honors `--addr` and `--base`, so it works with custom ports and base paths without extra configuration.
> [!WARNING]
> The `healthcheck` command does not work with `--health-cmd` flag due to a bug in Docker. You need to use the `healthcheck` configuration in the `docker-compose.yml` file. See [Docker issue](https://github.com/docker/cli/issues/3719) for more information.
> The `healthcheck` command does not work with the `--health-cmd` flag due to a bug in Docker. Use the `healthcheck` block in `docker-compose.yml` as shown above. See [docker/cli#3719](https://github.com/docker/cli/issues/3719) for details.
docs/guide/hostname.md
+4
View File
@@ -27,3 +27,7 @@ services:
```
:::
## Multi-Host and Agents
`--hostname` only relabels the host running **this** Dozzle process. Remote [agents](/guide/agent) advertise their own names — set `DOZZLE_HOSTNAME` (or `--hostname`) on each agent to control how it appears in the multi-host menu. In [swarm mode](/guide/swarm-mode) each node runs its own agent, so give each node a distinct hostname to tell them apart.
docs/guide/shell.md
+8
View File
@@ -31,3 +31,11 @@ services:
> [!NOTE]
> Shell access should work across all container types, including Docker, Kubernetes, and other orchestration platforms.
## Security
Anyone who can reach the Dozzle UI will be able to open a shell inside your containers — equivalent to `docker exec`. Before enabling `--enable-shell` on a publicly reachable Dozzle, put it behind [authentication](/guide/authentication). Role-based permissions can restrict shell access to specific users.
## Kubernetes
In k8s mode, shell access uses the Kubernetes API rather than `docker exec`. The target pod must contain an executable shell (`/bin/sh`, `/bin/bash`, etc.) — minimal images built `FROM scratch` or distroless images without a shell will not be attachable.
docs/guide/what-is-dozzle.md
+39 -7
View File
@@ -6,18 +6,50 @@ title: What is Dozzle?
Dozzle is an open-source project sponsored by Docker OSS. It is a lightweight, web-based log viewer designed to simplify monitoring and debugging containerized applications across Docker, Docker Swarm, and Kubernetes environments.
New here? Jump to [Getting Started](/guide/getting-started) to run it in under a minute.
## Key Features
**Real-time Monitoring**: Stream logs from running containers with instant updates through an intuitive web interface. Monitor CPU, memory, and network usage with live metrics and historical visualizations.
### Real-time Monitoring
**Flexible Deployment**: Deploy as a standalone server for single or multi-host Docker monitoring, enable automatic discovery in Docker Swarm clusters, or monitor pod logs in Kubernetes environments.
Stream logs from running containers with instant updates. Live CPU, memory, and network metrics with historical visualizations.
**Advanced Log Handling**: Automatically detects and formats JSON logs with intelligent color coding. Supports simple text logs, structured JSON logs, and multi-line grouped entries with powerful filtering and search capabilities.
### Flexible Deployment
**Multi-Host Support**: Monitor containers across multiple Docker hosts simultaneously through a distributed agent architecture using gRPC.
Run as a [standalone server](/guide/getting-started), a [Swarm](/guide/swarm-mode) deployment, a [Kubernetes](/guide/k8s) install, or with [remote agents](/guide/agent) across multiple hosts.
**Interactive Terminal**: Attach to running containers or execute commands directly through the web interface.
### Advanced Log Handling
**Lightweight & Fast**: Built with Go backend and Vue 3 frontend, Dozzle uses efficient streaming protocols (SSE/WebSocket) and requires minimal resources.
Automatic JSON detection and color coding, multi-line stack-trace grouping, [filters](/guide/filters), and an embedded [SQL engine](/guide/sql-engine) for ad-hoc queries.
Dozzle is easy to install and configure, making it an ideal solution for developers and system administrators seeking an efficient log viewer for their containerized environments. The tool is available under the MIT license and is actively maintained by its developer, Amir Raminfar.
### Multi-Host Support
Monitor containers across multiple Docker hosts from one UI. See [agents](/guide/agent).
### Interactive Terminal
Attach or exec into running containers from the browser. See [Shell Access](/guide/shell).
### Container Actions
Start, stop, restart, and update containers directly from the UI. See [Actions](/guide/actions).
### Alerts & Webhooks
Define log patterns that trigger notifications to Slack, Discord, email, and more. See [Alerts and Webhooks](/guide/alerts-and-webhooks).
### Authentication
Run open, or layer in [simple or forward-proxy auth](/guide/authentication) with role-based access control.
### Lightweight & Fast
Go backend, Vue 3 frontend, streaming over SSE and WebSocket — minimal resource footprint.
## Next Steps
- [Getting Started](/guide/getting-started)
- [Supported Environment Variables](/guide/supported-env-vars)
- [FAQ](/guide/faq)
Dozzle is MIT-licensed and actively maintained.