Install Netdata with Docker
Limitations running the Agent in Docker
We don’t officially support using Docker’s --user
option or Docker Compose’s user:
parameter with our images. While they may work, some features could be unavailable. The Agent drops privileges at startup, so most processes don’t run as UID 0 even without these options.
Create a new Netdata Agent container
You can create a new Agent container with docker run
or docker-compose
, then access the dashboard at http://NODE:19999
.
The Netdata container requires specific privileges and mounts to provide full monitoring capabilities equivalent to a direct host installation. Below is a list of required components and their purposes.
Privileges
Component | Privileges | Description |
---|---|---|
cgroups.plugin | host PID mode, SYS_ADMIN | Container network interfaces monitoring. Map virtual interfaces in the system namespace to interfaces inside containers. |
proc.plugin | host network mode | Host system networking stack monitoring. |
go.d.plugin | host network mode | Monitoring applications running on the host and inside containers. |
local-listeners | host network mode, SYS_PTRACE | Discovering local services/applications. Map open (listening) ports to running services/applications. |
network-viewer.plugin | host network mode, SYS_ADMIN | Discovering all current network sockets and building a network-map. |
Mounts
Component | Mounts | Description |
---|---|---|
netdata | /etc/os-release | Host info detection. |
diskspace.plugin | / | Host mount points monitoring. |
cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. |
go.d.plugin | /var/run/docker.sock | Docker Engine and containers monitoring. See docker collector. |
go.d.plugin | /var/log | Web servers logs tailing. See weblog collector. |
apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. |
proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). |
systemd-journal.plugin | /var/log | Viewing, exploring and analyzing systemd journal logs. |
systemd-journal.plugin | /run/dbus | Systemd-list-units function: information about all systemd units, including their active state, description, whether they are enabled, and more. |
go.d.plugin | /run/dbus | go.d/systemdunits |
Recommended way
Both methods create a volume for Netdata's configuration files
within the container at /etc/netdata
.
See the configure section for details. If you want to access the configuration files from your host machine, see host-editable configuration.
- docker run
- docker-compose
Using the docker run
command
Run the following command in your terminal to start a new container.
docker run -d --name=netdata \
--pid=host \
--network=host \
-v netdataconfig:/etc/netdata \
-v netdatalib:/var/lib/netdata \
-v netdatacache:/var/cache/netdata \
-v /:/host/root:ro,rslave \
-v /etc/passwd:/host/etc/passwd:ro \
-v /etc/group:/host/etc/group:ro \
-v /etc/localtime:/etc/localtime:ro \
-v /proc:/host/proc:ro \
-v /sys:/host/sys:ro \
-v /etc/os-release:/host/etc/os-release:ro \
-v /var/log:/host/var/log:ro \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /run/dbus:/run/dbus:ro \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--cap-add SYS_ADMIN \
--security-opt apparmor=unconfined \
netdata/netdata
Using the docker-compose
command
Create a file named docker-compose.yml
in your project directory and paste the code below. From your project
directory, start Netdata by running docker-compose up -d
.
version: '3'
services:
netdata:
image: netdata/netdata
container_name: netdata
pid: host
network_mode: host
restart: unless-stopped
cap_add:
- SYS_PTRACE
- SYS_ADMIN
security_opt:
- apparmor:unconfined
volumes:
- netdataconfig:/etc/netdata
- netdatalib:/var/lib/netdata
- netdatacache:/var/cache/netdata
- /:/host/root:ro,rslave
- /etc/passwd:/host/etc/passwd:ro
- /etc/group:/host/etc/group:ro
- /etc/localtime:/etc/localtime:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /etc/os-release:/host/etc/os-release:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
- /run/dbus:/run/dbus:ro
volumes:
netdataconfig:
netdatalib:
netdatacache:
📑 Note
If you plan to connect the node to Netdata Cloud, you can find the command with the right parameters by clicking the "Add Nodes" button in your Space's "Nodes" view.
With NVIDIA GPUs monitoring
Monitoring NVIDIA GPUs requires:
- Using official NVIDIA driver.
- Installing NVIDIA Container Toolkit.
- Allowing the Netdata container to access GPU resources.
- docker run
- docker-compose
Using the docker run
command
Add --gpus 'all,capabilities=utility'
to your docker run
.
Using the docker-compose
command
Add the following to the netdata service.
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
With host-editable configuration
Use a bind mount for /etc/netdata
rather than a volume.
This example assumes that you’ve created netdataconfig/
in your home directory.
mkdir netdataconfig
- docker run
- docker-compose
Using the docker run
command
Run the following command in your terminal to start a new container.
docker run -d --name=netdata \
--pid=host \
--network=host \
-v $(pwd)/netdataconfig/netdata:/etc/netdata \
-v netdatalib:/var/lib/netdata \
-v netdatacache:/var/cache/netdata \
-v /:/host/root:ro,rslave \
-v /etc/passwd:/host/etc/passwd:ro \
-v /etc/group:/host/etc/group:ro \
-v /etc/localtime:/etc/localtime:ro \
-v /proc:/host/proc:ro \
-v /sys:/host/sys:ro \
-v /etc/os-release:/host/etc/os-release:ro \
-v /var/log:/host/var/log:ro \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
--restart unless-stopped \
--cap-add SYS_PTRACE \
--cap-add SYS_ADMIN \
--security-opt apparmor=unconfined \
netdata/netdata
Using the docker-compose
command
Create a file named docker-compose.yml
in your project directory and paste the code below. From your project
directory, start Netdata by running docker-compose up -d
.
version: '3'
services:
netdata:
image: netdata/netdata
container_name: netdata
pid: host
network_mode: host
restart: unless-stopped
cap_add:
- SYS_PTRACE
- SYS_ADMIN
security_opt:
- apparmor:unconfined
volumes:
- ./netdataconfig/netdata:/etc/netdata
- netdatalib:/var/lib/netdata
- netdatacache:/var/cache/netdata
- /:/host/root:ro,rslave
- /etc/passwd:/host/etc/passwd:ro
- /etc/group:/host/etc/group:ro
- /etc/localtime:/etc/localtime:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /etc/os-release:/host/etc/os-release:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
volumes:
netdatalib:
netdatacache:
With SSL/TLS enabled HTTP Proxy
Below is an example of installing Netdata with an SSL reverse proxy and basic authentication using Docker.
Caddyfile Setup
Place the following Caddyfile
in /opt
, customizing the domain and adding your email for Let’s Encrypt. The certificate will renew automatically via the Caddy server.
netdata.example.org {
reverse_proxy host.docker.internal:19999
tls [email protected]
}
docker-compose.yml
After setting Caddyfile run this with docker-compose up -d
to have a fully functioning Netdata setup behind an HTTP reverse
proxy.
Make sure Netdata bind to docker0 interface if you've custom web.bind to
setting in netdata.conf
.
version: '3'
services:
caddy:
image: caddy:2
extra_hosts:
- "host.docker.internal:host-gateway" # To access netdata running with "network_mode: host".
ports:
- "80:80"
- "443:443"
volumes:
- /opt/Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
- caddy_config:/config
netdata:
image: netdata/netdata
container_name: netdata
pid: host
network_mode: host
restart: unless-stopped
cap_add:
- SYS_PTRACE
- SYS_ADMIN
security_opt:
- apparmor:unconfined
volumes:
- netdataconfig:/etc/netdata
- netdatalib:/var/lib/netdata
- netdatacache:/var/cache/netdata
- /:/host/root:ro,rslave
- /etc/passwd:/host/etc/passwd:ro
- /etc/group:/host/etc/group:ro
- /etc/localtime:/etc/localtime:ro
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /etc/os-release:/host/etc/os-release:ro
- /var/log:/host/var/log:ro
- /var/run/docker.sock:/var/run/docker.sock:ro
volumes:
caddy_data:
caddy_config:
netdataconfig:
netdatalib:
netdatacache:
Restrict access with basic auth
You can restrict access by following the official caddy guide and adding lines to Caddyfile.