Netdata

Overview

Netdata

Netdata collects Linux host metrics and shows live charts for CPU, memory, disks and network traffic. It stores metric history locally and evaluates built-in alerts. It suits a home server or a VPS where you want more detail than a simple uptime check. Compare it with Beszel for a lighter hub-and-agent approach.

This recipe runs the official 2.12.2 Agent and a mandatory Caddy password gateway. You do not need a Netdata Cloud account. Only the gateway is published, on loopback; the Agent API remains on a private Docker network. Collection and historical data work without claiming the Agent in Cloud.

What is included

• Native host CPU, RAM, disk and network collection through read-only host mounts.
• Local dbengine history, SQLite metadata, Agent identity and management keys in persistent volumes.
• Password protection of the local UI and APIs, healthchecks, backup and tested recovery.
• The bundled modern web interface. Its license differs from the Agent’s license.

Limits

The Agent is GPLv3+, but the modern UI is closed-source under NCUL1. The complete deployment is therefore classified as proprietary in this catalog. NCUL1 permits use with Netdata components and restricts modification and reverse engineering. See the upstream license explanation and NCUL1.

The Agent has no local OIDC, SAML or MFA setup here; the gateway supplies HTTP Basic authentication. Cloud login, Cloud SSO, shared saved dashboards, streaming children and external notification services are outside this recipe. The modern UI’s Live function tables require a claimed Agent and Cloud sign-in. There are no bundled native mobile or desktop clients. The tested UI and official documentation are English.

The monitored system is the Linux Docker host. On Docker Desktop that means its Linux VM. This is not complete Windows/macOS or physical-device monitoring. No Docker socket, extra SYS_ADMIN/SYS_PTRACE capabilities or unconfined profile is granted; some per-process and privileged collectors cannot read everything. Filesystems mounted after startup may require an Agent restart. See the official container privilege matrix.

Allow 512 MiB RAM at minimum, preferably 1 GiB, one CPU core and at least 5 GiB disk for a small single-host installation. Actual memory and retention depend on metric cardinality and collector load; these are planning estimates, not a hardware certification. See Agent sizing.

Data and privacy

The Agent runs unclaimed, opts out of Agent telemetry with DO_NOT_TRACK=1, and has no outbound route on its internal network. The browser UI can load resources from or contact Netdata domains, including a registry iframe carrying the Agent identifier and hostname. Do not interpret the Agent’s opt-out as a promise of no browser-side third-party traffic. See telemetry controls.

The Agent reads the host root, /proc, /sys, OS information and account names, and shares the host PID namespace. Its entrypoint starts as root and launches the Agent as UID/GID 201. Read-only does not mean non-sensitive: protect the image, local access, archives and API keys. Eight CRITICAL package findings were recorded across the two pinned images; the successful functional test does not resolve them.

Verification

On amd64, the complete recipe recorded real CPU/RAM charts and fixed historical CPU samples, then removed both data volumes. Recovery restored the original Agent identity, API-key hash and exact historical measurements. Anonymous UI/API requests were rejected; invalid archives, backup permissions, archive integrity, a safety backup and stopped-state backup were checked. ARM64, privileged collectors, Cloud integrations and notification delivery were not tested.

Step-by-step guide

Install Netdata

Prepare the Linux server

Use Docker Engine and Docker Compose 2.24 or newer on a supported Ubuntu or Debian release. The commands below target Ubuntu 22.04/24.04/26.04 and Debian 12/13; the runtime proof covers one amd64 Linux Docker host, not every distribution. Install Docker from its Ubuntu or Debian instructions. Check:

docker version
docker compose version

Docker administrators can control the host. This recipe reads host metrics and shares its PID namespace. Run it on a host you are authorized to monitor. Rootless Docker and restrictive host policies may limit collection and were not tested.

Put all recipe files in /srv/netdata, including config/, proxy/ and both recovery scripts. Before startup:

cd /srv/netdata
umask 077
cp .env.example .env
chmod 600 .env
chmod 644 config/Caddyfile config/netdata.conf
docker run --rm -it caddy:2.11.7-alpine caddy hash-password

Enter a unique password interactively. Save it in a password manager and put the resulting bcrypt hash in the single-quoted NETDATA_AUTH_HASH value in .env. Set your own username and hostname. The template hash is rejected before the gateway opens HTTP. The public configuration files contain no password and must be readable by the unprivileged gateway.

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --wait --wait-timeout 300
docker compose ps

First access and the local network

Open http://127.0.0.1:19999/v3/, enter the gateway username and the original password, then use the local dashboard without signing in to Netdata Cloud. Wait for native measurements to accumulate. The Agent is not claimed by this recipe. /healthz is public but contains no metrics; /api/v1/info and the dashboard require the password.

For another machine, prefer an SSH tunnel or an encrypted VPN. Do not expose Basic authentication over unencrypted public HTTP. Under Docker Desktop, measurements describe its Linux VM.

VPS

Keep the published port on loopback and connect through SSH before configuring HTTPS:

ssh -L 19999:127.0.0.1:19999 user@server

Allow only SSH and your intended HTTPS ports through the firewall. Do not publish the Agent’s internal port or grant Docker socket access. Protect and encrypt off-server backups.

Domain and HTTPS

Point your DNS name to the server. The supplied examples use metrics.example.com; replace it and retain the gateway’s authentication. The outer proxy must forward the client’s Authorization header. Verify an anonymous request to /api/v1/info still returns 401 and a password-authenticated request succeeds.

Caddy

Use proxy/Caddyfile with a host Caddy installation. It terminates HTTPS and forwards to 127.0.0.1:19999; the inner gateway continues to enforce the password.

Nginx

Use proxy/nginx.conf in your existing TLS-enabled server. Obtain a certificate first, replace the example certificate paths and domain, check nginx -t, then reload. The sample does not obtain certificates for you.

Traefik

Use proxy/traefik.yaml through Traefik’s file provider, with your existing websecure entrypoint and letsencrypt resolver. Join the Traefik container to this Compose project’s frontend network (normally netdata_frontend). The backend name gateway must resolve there. The internal Agent network stays separate.

Configuration and persistent data

config/netdata.conf configures the Agent and config/Caddyfile configures the password gateway. Both are mounted read-only inside their containers. Edit them on the host and recreate the affected service. The original image supplies its remaining default configuration; additional collector/alert files need explicit mounts and review.

The project-scoped netdata-lib volume stores /var/lib/netdata, including identity and API keys. netdata-cache stores /var/cache/netdata, including dbengine history and SQLite metadata. Both are required for a complete recovery. The host filesystem mounts are measurement inputs and are never included in these backup scripts.

Backup

bash backup.sh

The script briefly stops the gateway and Agent, archives both volumes and copies configuration, .env and Compose into one private archive under backups/. It restarts only services that were running. A stopped installation stays stopped. Archives have mode 600 and the backup directory mode 700. Encrypt a copy on a different server; an archive on this host does not protect against host loss.

Restore — replaces identity and history

Use a trusted archive and matching Agent version. Preserve the current installation before proceeding:

bash restore.sh -y backups/netdata-YYYYMMDDTHHMMSS-PID.tar.gz
docker compose ps

The script validates the archive before changing data, creates a safety backup, replaces both volumes and waits for health. Current configuration, password hash and image versions stay active. If the installation files were also lost, first extract and review configuration.env, compose.yaml and config/ from your own archive, restore .env with mode 600, and make the two public config files mode 644. Never source an untrusted archived environment file. Then run the data restore.

Update

Read the release notes and make an off-server backup. Change NETDATA_VERSION to the reviewed numeric version, then:

docker compose pull
docker compose up -d --wait --wait-timeout 300
docker compose logs --tail 100 netdata gateway

Review a Caddy version change separately in Compose. Recheck authenticated charts and anonymous denial after either image changes. A successful healthcheck alone does not establish that historical data survived.

Rollback

Keep the pre-update archive and recipe files. Stop the updated services, restore the reviewed old Compose/configuration and numeric Agent version, pull those pinned images, then run restore.sh -y with the pre-update archive. Do not point an older Agent at a possibly migrated newer database. Verify the original Agent identity and a historical interval after rollback.

Stop or remove

docker compose down stops the installation and keeps both data volumes. docker compose down --volumes permanently removes local identity and history. Keep and verify an off-server backup first. Remove .env, configuration and archives separately only when you intend to erase them. Never remove the host directories that the recipe reads for monitoring.

Official sources

Container deployment and collector privileges, dashboard access and Cloud-only features, Agent configuration.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Netdata troubleshooting

Start with docker compose ps and docker compose logs --tail 100 netdata gateway. Use the actual project directory and .env consistently. Do not paste credentials, API keys or full archives into issues.

Gateway refuses to start

Replace the placeholder with a bcrypt hash from caddy hash-password. Keep single quotes around the hash in .env, because its dollar signs must not be interpolated. Ensure config/Caddyfile is readable (mode 644). The official Caddy binary carries a file capability; this recipe retains NET_BIND_SERVICE even though it listens on 8080. Removing it can make binary execution fail with “Operation not permitted”.

401, including through HTTPS

Use the username from .env and the original password, not its hash. The gateway password can be rotated by replacing the hash and recreating gateway. An outer proxy must preserve Authorization; do not solve 401 by bypassing the gateway or publishing the Agent port.

No published port

The gateway needs its frontend bridge network as well as the Agent’s private network. An internal-only network does not publish a usable host port on some Docker versions. Keep both gateway networks; the Agent stays on the private one.

Dashboard loads slowly or never becomes network-idle

The UI uses live requests and may contact Netdata domains. Wait for visible charts, not network-idle. Open /v3/ directly for the bundled interface. Browser resource loading and Agent telemetry are separate. A Cloud sign-in button does not mean local collection requires a Cloud account. The modern UI’s Live function tables do require a claimed Agent and Cloud sign-in.

Missing process, device or container metrics

Read the official collector privilege matrix. This recipe does not grant extra SYS_ADMIN/SYS_PTRACE, unconfined profiles, host networking or a Docker socket. Permission warnings for some process descriptors are expected. Under Docker Desktop, the Linux VM is monitored. Some newly mounted host filesystems appear only after restarting the Agent. Do not assume all physical hardware or per-container labels were verified.

Host information is wrong

Check NETDATA_HOSTNAME and authenticated /api/v1/info. Compare CPU count with the mounted host /proc, not container resource limits alone. The host root, /proc, /sys and OS-release mounts must refer to the same Docker host. Remote Docker daemons resolve bind paths on the daemon machine, not your client laptop.

Restore rejected or history missing

Keep the original archive unchanged. Restore requires both volume archives and the configuration reference. Absolute paths, traversal and links in the metric archives are rejected. A failed validation must leave the running installation untouched. Check disk space and use matching pinned image versions; restoring only /var/lib/netdata loses dbengine history in /var/cache/netdata.

Security scan findings

The recorded scan found eight CRITICAL package findings across the pinned Agent and gateway images. Some are repeat CVEs across packages. Track upstream fixes and rescan reviewed images; do not treat startup or restore success as proof the findings are fixed.