74 lines
2.6 KiB
Markdown
74 lines
2.6 KiB
Markdown
# Containers (Docker)
|
|
|
|
PearData can chart per-container CPU and memory and show **human names** (e.g. `dozzle`) instead of short hashes.
|
|
|
|
## Requirements
|
|
|
|
On the **agent** host:
|
|
|
|
1. Docker (or Podman with a compatible socket) installed
|
|
2. Agent user can read the engine socket
|
|
3. `PEARDATA_DOCKER=1` in the agent `.env`
|
|
|
|
The [one-line installer](../docs/GETTING-STARTED.md) does this automatically when Docker is detected:
|
|
|
|
- Adds `peardata` to the **`docker`** group
|
|
- Sets unit `SupplementaryGroups=… docker`
|
|
- Writes `PEARDATA_DOCKER=1` and `PEARDATA_DOCKER_SOCKET=…`
|
|
|
|
Then restart: `sudo systemctl restart peardata`.
|
|
|
|
## Already installed without Docker setup?
|
|
|
|
```bash
|
|
sudo usermod -aG docker peardata
|
|
# /opt/peardata/.env — add or set:
|
|
# PEARDATA_DOCKER=1
|
|
# PEARDATA_DOCKER_SOCKET=/var/run/docker.sock
|
|
# Unit must include docker in SupplementaryGroups (re-run installer --server, or edit peardata.service)
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl restart peardata
|
|
```
|
|
|
|
Confirm names loaded:
|
|
|
|
```bash
|
|
sudo journalctl -u peardata -n 50 --no-pager | grep -i docker
|
|
```
|
|
|
|
You should see a line like `Docker container names loaded` with a count.
|
|
|
|
## What you see in the UI
|
|
|
|
| Surface | Behavior |
|
|
|---------|----------|
|
|
| **Charts → Containers** | Cards titled `dozzle · CPU`, `dozzle · memory`; family groups by container name |
|
|
| Card subtitle | Units only (chart id stays in the tooltip for debugging) |
|
|
| Explore dropdown | Human titles, not `docker.cpu.<hash>` |
|
|
| Cgroup charts | Same name enrichment when the socket is readable |
|
|
|
|
Chart **ids** remain `docker.cpu.<shortId>` / `docker.mem.<shortId>` so history stays stable when a container is recreated with the same id prefix.
|
|
|
|
## How names are loaded (agent)
|
|
|
|
PearData tries, in order:
|
|
|
|
1. **Docker Engine API** over the unix socket (raw HTTP — works under Bare)
|
|
2. **`docker ps`** CLI
|
|
3. On-disk `config.v2.json` under `/var/lib/docker/containers` (if readable)
|
|
|
|
Then each container label prefers:
|
|
|
|
1. Compose / Swarm / Kubernetes service labels (`web`, `web · 2`)
|
|
2. Docker `Names` (e.g. `/dozzle` → `dozzle`)
|
|
3. Image short name
|
|
4. Fallback `container <12-char id>` if none of the sources worked
|
|
|
|
If the UI still shows `container <hash>`, the agent could not reach Docker. Check the journal for `Docker container names loaded` / `Container names loaded for cgroups`, then fix group/socket and restart.
|
|
|
|
## Related
|
|
|
|
- Env: [CONFIGURATION.md](../docs/CONFIGURATION.md) (`PEARDATA_DOCKER*`)
|
|
- Collector: [EXTENDING.md](../docs/EXTENDING.md)
|
|
- Taxonomy section **Containers**: [DASHBOARD.md](../docs/DASHBOARD.md)
|