| 1 | import Tabs from '@theme/Tabs'; |
| 2 | import TabItem from '@theme/TabItem'; |
| 3 | |
| 4 | # Install Netdata with Docker |
| 5 | |
| 6 | ## Limitations running the Agent in Docker |
| 7 | |
| 8 | 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. |
| 9 | |
| 10 | ## Create a new Netdata Agent container |
| 11 | |
| 12 | You can create a new Agent container with `docker run` or `docker-compose`, then access the dashboard at `http://NODE:19999`. |
| 13 | |
| 14 | 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. |
| 15 | |
| 16 | <details open> |
| 17 | <summary>Privileges</summary> |
| 18 | |
| 19 | | Component | Privileges | Description | |
| 20 | |:---------------------:|:-----------------------------:|--------------------------------------------------------------------------------------------------------------------------| |
| 21 | | cgroups.plugin | host PID mode, SYS_ADMIN | Container network interfaces monitoring. Map virtual interfaces in the system namespace to interfaces inside containers. | |
| 22 | | proc.plugin | host network mode | Host system networking stack monitoring. | |
| 23 | | go.d.plugin | host network mode | Monitoring applications running on the host and inside containers. | |
| 24 | | local-listeners | host network mode, SYS_PTRACE | Discovering local services/applications. Map open (listening) ports to running services/applications. | |
| 25 | | network-viewer.plugin | host network mode, SYS_ADMIN | Discovering all current network sockets and building a network-map. | |
| 26 | |
| 27 | </details> |
| 28 | |
| 29 | <details open> |
| 30 | <summary>Mounts</summary> |
| 31 | |
| 32 | | Component | Mounts | Description | |
| 33 | |:----------------------:|:--------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------| |
| 34 | | netdata | /etc/os-release | Host info detection. | |
| 35 | | diskspace.plugin | / | Host mount points monitoring. | |
| 36 | | cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. | |
| 37 | | go.d.plugin | /var/run/docker.sock | Docker Engine and containers monitoring. See [docker](https://github.com/netdata/go.d.plugin/tree/master/modules/docker#readme) collector. | |
| 38 | | go.d.plugin | /var/log | Web servers logs tailing. See [weblog](https://github.com/netdata/go.d.plugin/tree/master/modules/weblog#readme) collector. | |
| 39 | | apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. | |
| 40 | | proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). | |
| 41 | | systemd-journal.plugin | /var/log | Viewing, exploring and analyzing systemd journal logs. | |
| 42 | | systemd-units.plugin | /run/dbus | Systemd-list-units function: information about all systemd units, including their active state, description, whether they are enabled, and more. | |
| 43 | | go.d.plugin | /run/dbus | [go.d/systemdunits](https://github.com/netdata/go.d.plugin/tree/master/modules/systemdunits#readme) | |
| 44 | |
| 45 | </details> |
| 46 | |
| 47 | ### Recommended way |
| 48 | |
| 49 | Both methods create a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files |
| 50 | _within the container_ at `/etc/netdata`. |
| 51 | See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from your _host_ machine, see [host-editable configuration](#with-host-editable-configuration). |
| 52 | |
| 53 | :::info If you remove `pid: host` |
| 54 | If you choose **not** to use `pid: host`, you **must** add [`--init`](https://docs.docker.com/reference/cli/docker/container/run/#init) (or [`init: true`](https://docs.docker.com/reference/compose-file/services/#init) in Compose). |
| 55 | |
| 56 | `--init` installs a minimal init system that reaps processes and ensures stable container operation. |
| 57 | ::: |
| 58 | |
| 59 | <Tabs> |
| 60 | <TabItem value="docker_run" label="docker run"> |
| 61 | |
| 62 | <h3> Using the <code>docker run</code> command </h3> |
| 63 | |
| 64 | Run the following command in your terminal to start a new container. |
| 65 | |
| 66 | ```bash |
| 67 | docker run -d --name=netdata \ |
| 68 | --pid=host \ |
| 69 | --network=host \ |
| 70 | -v netdataconfig:/etc/netdata \ |
| 71 | -v netdatalib:/var/lib/netdata \ |
| 72 | -v netdatacache:/var/cache/netdata \ |
| 73 | -v /:/host/root:ro,rslave \ |
| 74 | -v /etc/passwd:/host/etc/passwd:ro \ |
| 75 | -v /etc/group:/host/etc/group:ro \ |
| 76 | -v /etc/localtime:/etc/localtime:ro \ |
| 77 | -v /proc:/host/proc:ro \ |
| 78 | -v /sys:/host/sys:ro \ |
| 79 | -v /etc/os-release:/host/etc/os-release:ro \ |
| 80 | -v /var/log:/host/var/log:ro \ |
| 81 | -v /var/run/docker.sock:/var/run/docker.sock:ro \ |
| 82 | -v /run/dbus:/run/dbus:ro \ |
| 83 | --restart unless-stopped \ |
| 84 | --cap-add SYS_PTRACE \ |
| 85 | --cap-add SYS_ADMIN \ |
| 86 | --security-opt apparmor=unconfined \ |
| 87 | netdata/netdata |
| 88 | ``` |
| 89 | |
| 90 | </TabItem> |
| 91 | <TabItem value="docker compose" label="docker-compose"> |
| 92 | |
| 93 | <h3> Using the <code>docker-compose</code> command</h3> |
| 94 | |
| 95 | Create a file named `docker-compose.yml` in your project directory and paste the code below. From your project |
| 96 | directory, start Netdata by running `docker-compose up -d`. |
| 97 | |
| 98 | ```yaml |
| 99 | version: '3' |
| 100 | services: |
| 101 | netdata: |
| 102 | image: netdata/netdata |
| 103 | container_name: netdata |
| 104 | pid: host |
| 105 | network_mode: host |
| 106 | restart: unless-stopped |
| 107 | cap_add: |
| 108 | - SYS_PTRACE |
| 109 | - SYS_ADMIN |
| 110 | security_opt: |
| 111 | - apparmor:unconfined |
| 112 | volumes: |
| 113 | - netdataconfig:/etc/netdata |
| 114 | - netdatalib:/var/lib/netdata |
| 115 | - netdatacache:/var/cache/netdata |
| 116 | - /:/host/root:ro,rslave |
| 117 | - /etc/passwd:/host/etc/passwd:ro |
| 118 | - /etc/group:/host/etc/group:ro |
| 119 | - /etc/localtime:/etc/localtime:ro |
| 120 | - /proc:/host/proc:ro |
| 121 | - /sys:/host/sys:ro |
| 122 | - /etc/os-release:/host/etc/os-release:ro |
| 123 | - /var/log:/host/var/log:ro |
| 124 | - /var/run/docker.sock:/var/run/docker.sock:ro |
| 125 | - /run/dbus:/run/dbus:ro |
| 126 | |
| 127 | volumes: |
| 128 | netdataconfig: |
| 129 | netdatalib: |
| 130 | netdatacache: |
| 131 | ``` |
| 132 | |
| 133 | </TabItem> |
| 134 | </Tabs> |
| 135 | |
| 136 | :::tip |
| 137 | |
| 138 | - When using `netdata/netdata` without a tag, Docker pulls the latest image by default. To run the stable version, replace it with `netdata/netdata:stable`. |
| 139 | - 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. |
| 140 | |
| 141 | ::: |
| 142 | |
| 143 | ### With NVIDIA GPUs monitoring |
| 144 | |
| 145 | Monitoring NVIDIA GPUs requires: |
| 146 | |
| 147 | - Using official [NVIDIA driver](https://www.nvidia.com/Download/index.aspx). |
| 148 | - Installing [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html). |
| 149 | - Allowing the Netdata container to access GPU resources. |
| 150 | |
| 151 | <Tabs> |
| 152 | <TabItem value="docker_run" label="docker run"> |
| 153 | |
| 154 | <h3> Using the <code>docker run</code> command </h3> |
| 155 | |
| 156 | Add `--gpus 'all,capabilities=utility'` to your `docker run`. |
| 157 | |
| 158 | </TabItem> |
| 159 | <TabItem value="docker compose" label="docker-compose"> |
| 160 | |
| 161 | <h3> Using the <code>docker-compose</code> command</h3> |
| 162 | |
| 163 | Add the following to the netdata service. |
| 164 | |
| 165 | ```yaml |
| 166 | deploy: |
| 167 | resources: |
| 168 | reservations: |
| 169 | devices: |
| 170 | - driver: nvidia |
| 171 | count: all |
| 172 | capabilities: [gpu] |
| 173 | ``` |
| 174 | |
| 175 | </TabItem> |
| 176 | </Tabs> |
| 177 | |
| 178 | ### With host-editable configuration |
| 179 | |
| 180 | Use a [bind mount](https://docs.docker.com/storage/bind-mounts/) for `/etc/netdata` rather than a volume. |
| 181 | |
| 182 | This example assumes that you’ve created `netdataconfig/` in your home directory. |
| 183 | |
| 184 | ```bash |
| 185 | mkdir netdataconfig |
| 186 | ``` |
| 187 | |
| 188 | <Tabs> |
| 189 | <TabItem value="docker_run" label="docker run"> |
| 190 | |
| 191 | <h3> Using the <code>docker run</code> command </h3> |
| 192 | |
| 193 | Run the following command in your terminal to start a new container. |
| 194 | |
| 195 | ```bash |
| 196 | docker run -d --name=netdata \ |
| 197 | --pid=host \ |
| 198 | --network=host \ |
| 199 | -v $(pwd)/netdataconfig/netdata:/etc/netdata \ |
| 200 | -v netdatalib:/var/lib/netdata \ |
| 201 | -v netdatacache:/var/cache/netdata \ |
| 202 | -v /:/host/root:ro,rslave \ |
| 203 | -v /etc/passwd:/host/etc/passwd:ro \ |
| 204 | -v /etc/group:/host/etc/group:ro \ |
| 205 | -v /etc/localtime:/etc/localtime:ro \ |
| 206 | -v /proc:/host/proc:ro \ |
| 207 | -v /sys:/host/sys:ro \ |
| 208 | -v /etc/os-release:/host/etc/os-release:ro \ |
| 209 | -v /var/log:/host/var/log:ro \ |
| 210 | -v /var/run/docker.sock:/var/run/docker.sock:ro \ |
| 211 | --restart unless-stopped \ |
| 212 | --cap-add SYS_PTRACE \ |
| 213 | --cap-add SYS_ADMIN \ |
| 214 | --security-opt apparmor=unconfined \ |
| 215 | netdata/netdata |
| 216 | ``` |
| 217 | |
| 218 | </TabItem> |
| 219 | <TabItem value="docker compose" label="docker-compose"> |
| 220 | |
| 221 | <h3> Using the <code>docker-compose</code> command</h3> |
| 222 | |
| 223 | Create a file named `docker-compose.yml` in your project directory and paste the code below. From your project |
| 224 | directory, start Netdata by running `docker-compose up -d`. |
| 225 | |
| 226 | ```yaml |
| 227 | version: '3' |
| 228 | services: |
| 229 | netdata: |
| 230 | image: netdata/netdata |
| 231 | container_name: netdata |
| 232 | pid: host |
| 233 | network_mode: host |
| 234 | restart: unless-stopped |
| 235 | cap_add: |
| 236 | - SYS_PTRACE |
| 237 | - SYS_ADMIN |
| 238 | security_opt: |
| 239 | - apparmor:unconfined |
| 240 | volumes: |
| 241 | - ./netdataconfig/netdata:/etc/netdata |
| 242 | - netdatalib:/var/lib/netdata |
| 243 | - netdatacache:/var/cache/netdata |
| 244 | - /:/host/root:ro,rslave |
| 245 | - /etc/passwd:/host/etc/passwd:ro |
| 246 | - /etc/group:/host/etc/group:ro |
| 247 | - /etc/localtime:/etc/localtime:ro |
| 248 | - /proc:/host/proc:ro |
| 249 | - /sys:/host/sys:ro |
| 250 | - /etc/os-release:/host/etc/os-release:ro |
| 251 | - /var/log:/host/var/log:ro |
| 252 | - /var/run/docker.sock:/var/run/docker.sock:ro |
| 253 | |
| 254 | volumes: |
| 255 | netdatalib: |
| 256 | netdatacache: |
| 257 | ``` |
| 258 | |
| 259 | </TabItem> |
| 260 | </Tabs> |
| 261 | |
| 262 | :::tip |
| 263 | |
| 264 | - When using `netdata/netdata` without a tag, Docker pulls the latest image by default. To run the stable version, replace it with `netdata/netdata:stable`. |
| 265 | - 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. |
| 266 | |
| 267 | ::: |
| 268 | |
| 269 | ### With SSL/TLS enabled HTTP Proxy |
| 270 | |
| 271 | Below is an example of installing Netdata with an **SSL reverse proxy** and **basic authentication** using Docker. |
| 272 | |
| 273 | #### Caddyfile Setup |
| 274 | |
| 275 | 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. |
| 276 | |
| 277 | ```caddyfile |
| 278 | netdata.example.org { |
| 279 | reverse_proxy host.docker.internal:19999 |
| 280 | tls admin@example.org |
| 281 | } |
| 282 | ``` |
| 283 | |
| 284 | #### docker-compose.yml |
| 285 | |
| 286 | After setting Caddyfile run this with `docker-compose up -d` to have a fully functioning Netdata setup behind an HTTP reverse |
| 287 | proxy. |
| 288 | |
| 289 | Make sure Netdata bind to docker0 interface if you've custom `web.bind to` setting in `netdata.conf`. |
| 290 | |
| 291 | ```yaml |
| 292 | version: '3' |
| 293 | services: |
| 294 | caddy: |
| 295 | image: caddy:2 |
| 296 | extra_hosts: |
| 297 | - "host.docker.internal:host-gateway" # To access netdata running with "network_mode: host". |
| 298 | ports: |
| 299 | - "80:80" |
| 300 | - "443:443" |
| 301 | volumes: |
| 302 | - /opt/Caddyfile:/etc/caddy/Caddyfile |
| 303 | - caddy_data:/data |
| 304 | - caddy_config:/config |
| 305 | netdata: |
| 306 | image: netdata/netdata |
| 307 | container_name: netdata |
| 308 | pid: host |
| 309 | network_mode: host |
| 310 | restart: unless-stopped |
| 311 | cap_add: |
| 312 | - SYS_PTRACE |
| 313 | - SYS_ADMIN |
| 314 | security_opt: |
| 315 | - apparmor:unconfined |
| 316 | volumes: |
| 317 | - netdataconfig:/etc/netdata |
| 318 | - netdatalib:/var/lib/netdata |
| 319 | - netdatacache:/var/cache/netdata |
| 320 | - /:/host/root:ro,rslave |
| 321 | - /etc/passwd:/host/etc/passwd:ro |
| 322 | - /etc/group:/host/etc/group:ro |
| 323 | - /etc/localtime:/etc/localtime:ro |
| 324 | - /proc:/host/proc:ro |
| 325 | - /sys:/host/sys:ro |
| 326 | - /etc/os-release:/host/etc/os-release:ro |
| 327 | - /var/log:/host/var/log:ro |
| 328 | - /var/run/docker.sock:/var/run/docker.sock:ro |
| 329 | volumes: |
| 330 | caddy_data: |
| 331 | caddy_config: |
| 332 | netdataconfig: |
| 333 | netdatalib: |
| 334 | netdatacache: |
| 335 | ``` |
| 336 | |
| 337 | #### Restrict access with basic auth |
| 338 | |
| 339 | You can restrict access by following the [official caddy guide](https://caddyserver.com/docs/caddyfile/directives/basicauth#basicauth) and adding lines to Caddyfile. |
| 340 | |
| 341 | ### With Docker socket proxy |
| 342 | |
| 343 | :::note |
| 344 | |
| 345 | Using Netdata with a Docker socket proxy may cause some features to not work as expected. It hasn't been fully tested by the Netdata team. |
| 346 | |
| 347 | ::: |
| 348 | |
| 349 | For better security, deploy a **Docker socket proxy** with a tool like [HAProxy](/docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md) or [CetusGuard](https://github.com/hectorm/cetusguard). This ensures the socket is **read-only** and restricted to the `/containers` endpoint. |
| 350 | |
| 351 | Exposing the socket to a proxy is safer because Netdata’s TCP port is accessible outside the Docker network, while the proxy container remains isolated within it. |
| 352 | |
| 353 | #### HAProxy |
| 354 | |
| 355 | ```yaml |
| 356 | version: '3' |
| 357 | services: |
| 358 | netdata: |
| 359 | image: netdata/netdata |
| 360 | container_name: netdata |
| 361 | pid: host |
| 362 | network_mode: host |
| 363 | restart: unless-stopped |
| 364 | cap_add: |
| 365 | - SYS_PTRACE |
| 366 | - SYS_ADMIN |
| 367 | security_opt: |
| 368 | - apparmor:unconfined |
| 369 | volumes: |
| 370 | - netdataconfig:/etc/netdata |
| 371 | - netdatalib:/var/lib/netdata |
| 372 | - netdatacache:/var/cache/netdata |
| 373 | - /:/host/root:ro,rslave |
| 374 | - /etc/passwd:/host/etc/passwd:ro |
| 375 | - /etc/group:/host/etc/group:ro |
| 376 | - /etc/localtime:/etc/localtime:ro |
| 377 | - /proc:/host/proc:ro |
| 378 | - /sys:/host/sys:ro |
| 379 | - /etc/os-release:/host/etc/os-release:ro |
| 380 | - /var/log:/host/var/log:ro |
| 381 | environment: |
| 382 | - DOCKER_HOST=localhost:2375 |
| 383 | proxy: |
| 384 | network_mode: host |
| 385 | image: tecnativa/docker-socket-proxy |
| 386 | volumes: |
| 387 | - /var/run/docker.sock:/var/run/docker.sock:ro |
| 388 | environment: |
| 389 | - CONTAINERS=1 |
| 390 | |
| 391 | volumes: |
| 392 | netdataconfig: |
| 393 | netdatalib: |
| 394 | netdatacache: |
| 395 | ``` |
| 396 | |
| 397 | :::tip |
| 398 | |
| 399 | - When using `netdata/netdata` without a tag, Docker pulls the latest image by default. To run the stable version, replace it with `netdata/netdata:stable`. |
| 400 | - Replace `2375` with the port of your proxy. |
| 401 | |
| 402 | ::: |
| 403 | |
| 404 | #### CetusGuard |
| 405 | |
| 406 | :::note |
| 407 | |
| 408 | This deployment method is supported by the community |
| 409 | |
| 410 | ::: |
| 411 | |
| 412 | ```yaml |
| 413 | version: '3' |
| 414 | services: |
| 415 | netdata: |
| 416 | image: netdata/netdata |
| 417 | container_name: netdata |
| 418 | pid: host |
| 419 | network_mode: host |
| 420 | restart: unless-stopped |
| 421 | cap_add: |
| 422 | - SYS_PTRACE |
| 423 | - SYS_ADMIN |
| 424 | security_opt: |
| 425 | - apparmor:unconfined |
| 426 | volumes: |
| 427 | - netdataconfig:/etc/netdata |
| 428 | - netdatalib:/var/lib/netdata |
| 429 | - netdatacache:/var/cache/netdata |
| 430 | - /:/host/root:ro,rslave |
| 431 | - /etc/passwd:/host/etc/passwd:ro |
| 432 | - /etc/group:/host/etc/group:ro |
| 433 | - /etc/localtime:/etc/localtime:ro |
| 434 | - /proc:/host/proc:ro |
| 435 | - /sys:/host/sys:ro |
| 436 | - /etc/os-release:/host/etc/os-release:ro |
| 437 | - /var/log:/host/var/log:ro |
| 438 | environment: |
| 439 | - DOCKER_HOST=localhost:2375 |
| 440 | cetusguard: |
| 441 | image: hectorm/cetusguard:v1 |
| 442 | network_mode: host |
| 443 | read_only: true |
| 444 | volumes: |
| 445 | - /var/run/docker.sock:/var/run/docker.sock:ro |
| 446 | environment: |
| 447 | CETUSGUARD_BACKEND_ADDR: unix:///var/run/docker.sock |
| 448 | CETUSGUARD_FRONTEND_ADDR: tcp://:2375 |
| 449 | CETUSGUARD_RULES: | |
| 450 | ! Inspect a container |
| 451 | GET %API_PREFIX_CONTAINERS%/%CONTAINER_ID_OR_NAME%/json |
| 452 | |
| 453 | volumes: |
| 454 | netdataconfig: |
| 455 | netdatalib: |
| 456 | netdatacache: |
| 457 | ``` |
| 458 | |
| 459 | :::tip |
| 460 | |
| 461 | You can run the socket proxy in its own Docker Compose file and leave it on a private network that you can add to other services that require access. |
| 462 | |
| 463 | ::: |
| 464 | |
| 465 | ### Rootless mode |
| 466 | |
| 467 | Netdata can be run successfully in a non-root environment, such as [rootless Docker](https://docs.docker.com/engine/security/rootless/). |
| 468 | |
| 469 | Netdata can run in a rootless Docker environment, but its data collection is limited due to restricted access to resources requiring elevated privileges. |
| 470 | The following components won't work: |
| 471 | |
| 472 | - container network interfaces monitoring (cgroup-network helper) |
| 473 | - disk I/O and file descriptors of applications and processes (apps.plugin) |
| 474 | - debugfs.plugin |
| 475 | - freeipmi.plugin |
| 476 | - perf.plugin |
| 477 | - slabinfo.plugin |
| 478 | - systemd-journal.plugin |
| 479 | |
| 480 | This method creates a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files |
| 481 | _within the container_ at `/etc/netdata`. |
| 482 | See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from your _host_ machine, see [host-editable configuration](#with-host-editable-configuration). |
| 483 | |
| 484 | <Tabs> |
| 485 | <TabItem value="docker_run" label="docker run"> |
| 486 | |
| 487 | <h3> Using the <code>docker run</code> command </h3> |
| 488 | |
| 489 | Run the following command in your terminal to start a new container. |
| 490 | |
| 491 | ```bash |
| 492 | docker run -d --name=netdata \ |
| 493 | --hostname=$(hostname) \ |
| 494 | -p 19999:19999 \ |
| 495 | -v netdataconfig:/etc/netdata \ |
| 496 | -v netdatalib:/var/lib/netdata \ |
| 497 | -v netdatacache:/var/cache/netdata \ |
| 498 | -v /etc/passwd:/host/etc/passwd:ro \ |
| 499 | -v /etc/group:/host/etc/group:ro \ |
| 500 | -v /etc/localtime:/etc/localtime:ro \ |
| 501 | -v /proc:/host/proc:ro \ |
| 502 | -v /sys:/host/sys:ro \ |
| 503 | -v /etc/os-release:/host/etc/os-release:ro \ |
| 504 | -v /run/user/$UID/docker.sock:/var/run/docker.sock:ro \ |
| 505 | --restart unless-stopped \ |
| 506 | --security-opt apparmor=unconfined \ |
| 507 | netdata/netdata |
| 508 | ``` |
| 509 | |
| 510 | </TabItem> |
| 511 | |
| 512 | </Tabs> |
| 513 | |
| 514 | :::tip |
| 515 | |
| 516 | - When using `netdata/netdata` without a tag, Docker pulls the latest image by default. To run the stable version, replace it with `netdata/netdata:stable`. |
| 517 | - 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. |
| 518 | |
| 519 | ::: |
| 520 | |
| 521 | ## Docker tags |
| 522 | |
| 523 | See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata). |
| 524 | |
| 525 | The official `netdata/netdata` Docker image provides the following named tags: |
| 526 | |
| 527 | | Tag | Description | |
| 528 | |:--------:|---------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 529 | | `stable` | the most recently published stable build. | |
| 530 | | `edge` | the most recently published nightly build. In most cases, this is updated daily at around 01:00 UTC. | |
| 531 | | `latest` | the most recently published build, whether it’s a stable build or a nightly build. This is what Docker will use by default if you do not specify a tag. | |
| 532 | | `vX.Y.Z` | the full version of the release (for example, `v1.40.0`). | |
| 533 | | `vX.Y` | the major and minor version (for example, `v1.40`). | |
| 534 | | `vX` | just the major version (for example, `v1`). | |
| 535 | |
| 536 | Minor and major version tags update with each matching release. For example, if `v1.40.1` is published, the `v1.40` tag moves from `v1.40.0` to `v1.40.1`. |
| 537 | |
| 538 | ## Update your Netdata Docker container |
| 539 | |
| 540 | Docker containers do not auto-update. To update, you pull a new image and recreate the container. |
| 541 | |
| 542 | :::important |
| 543 | |
| 544 | Persistent volumes (`netdataconfig`, `netdatalib`, `netdatacache`) preserve your configuration and metrics across container recreation. If you followed the recommended installation, these volumes are already set up. |
| 545 | |
| 546 | ::: |
| 547 | |
| 548 | <Tabs> |
| 549 | <TabItem value="docker_run" label="docker run"> |
| 550 | |
| 551 | 1. Pull the latest image: |
| 552 | |
| 553 | ```bash |
| 554 | docker pull netdata/netdata:stable |
| 555 | ``` |
| 556 | |
| 557 | 2. Stop and remove the existing container: |
| 558 | |
| 559 | ```bash |
| 560 | docker stop netdata && docker rm netdata |
| 561 | ``` |
| 562 | |
| 563 | 3. Recreate the container using the same `docker run` command you originally used (see [Create a new Netdata Agent container](#create-a-new-netdata-agent-container) above). |
| 564 | |
| 565 | </TabItem> |
| 566 | <TabItem value="docker_compose" label="docker-compose"> |
| 567 | |
| 568 | ```bash |
| 569 | docker-compose pull && docker-compose up -d |
| 570 | ``` |
| 571 | |
| 572 | The `docker-compose.yml` file preserves all configuration options. |
| 573 | |
| 574 | </TabItem> |
| 575 | </Tabs> |
| 576 | |
| 577 | Check the running Agent version: |
| 578 | |
| 579 | ```bash |
| 580 | docker exec netdata netdata -W buildinfo |
| 581 | ``` |
| 582 | |
| 583 | :::tip |
| 584 | |
| 585 | Use the `stable` tag to pull only stable releases. The `latest` tag (the default) may include nightly builds. See [Docker tags](#docker-tags) for all available tags. |
| 586 | |
| 587 | ::: |
| 588 | |
| 589 | :::note |
| 590 | |
| 591 | If Netdata Cloud shows a **Critical update** notification, your Agent version is below the minimum required version for optimal Cloud functionality. Nightly builds may trigger this notification even when up to date. Switching to the `stable` tag resolves this. |
| 592 | |
| 593 | ::: |
| 594 | |
| 595 | :::note |
| 596 | |
| 597 | If you manage containers through a third-party platform (such as CasaOS, Portainer, or ZimaBoard), use that platform's update interface. The Netdata image must use our official image tags to receive updates. |
| 598 | |
| 599 | ::: |
| 600 | |
| 601 | ## Configure Agent Containers |
| 602 | |
| 603 | If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container) and need to edit its configuration, first attach to the container with `docker exec`, replacing `netdata` with your container’s name. |
| 604 | |
| 605 | ```bash |
| 606 | docker exec -it netdata bash |
| 607 | cd /etc/netdata |
| 608 | ./edit-config netdata.conf |
| 609 | ``` |
| 610 | |
| 611 | Restart the Agent to apply changes: exit the container if necessary, then run `docker restart netdata`. |
| 612 | |
| 613 | ### Change the default hostname |
| 614 | |
| 615 | A container’s hostname appears in both the local dashboard and Netdata Cloud. |
| 616 | |
| 617 | To change it after creation, stop and remove the container—it’s safe! Your configuration and metrics stay intact in persistent volumes and will reattach when you recreate the container. |
| 618 | |
| 619 | If you use `docker-run`, use the `--hostname` option with `docker run`. |
| 620 | |
| 621 | ```bash |
| 622 | docker run -d --name=netdata \ |
| 623 | --hostname=my_docker_netdata |
| 624 | ``` |
| 625 | |
| 626 | If you use `docker-compose`, add a `hostname:` key/value pair into your `docker-compose.yml` file, then create the |
| 627 | container again using `docker-compose up -d`. |
| 628 | |
| 629 | ```yaml |
| 630 | version: '3' |
| 631 | services: |
| 632 | netdata: |
| 633 | image: netdata/netdata |
| 634 | container_name: netdata |
| 635 | hostname: my_docker_compose_netdata |
| 636 | ``` |
| 637 | |
| 638 | If you prefer not to recreate the container, edit the Agent’s `netdata.conf` file. See [configuring Agent containers](#configure-agent-containers) for the right method based on how you created it. |
| 639 | |
| 640 | Alternatively, use the **host’s hostname** by mounting `/etc/hostname` in the container: |
| 641 | |
| 642 | - **With `docker run`**, add: |
| 643 | ```sh |
| 644 | --volume /etc/hostname:/host/etc/hostname:ro |
| 645 | ``` |
| 646 | - **With Docker Compose**, add this to the `volumes` section: |
| 647 | ```yaml |
| 648 | - /etc/hostname:/host/etc/hostname:ro |
| 649 | ``` |
| 650 | |
| 651 | ## Adding extra packages at runtime |
| 652 | |
| 653 | By default, Netdata’s official container images exclude some optional runtime dependencies. You can install them at runtime by setting the `NETDATA_EXTRA_DEB_PACKAGES` environment variable. |
| 654 | |
| 655 | Commonly useful packages: |
| 656 | |
| 657 | - `apcupsd` – Monitors APC UPS devices. |
| 658 | - `lm-sensors` – Monitors hardware sensors. |
| 659 | - `netcat-openbsd` – Enables IRC alerts. |
| 660 | |
| 661 | ## Health Checks |
| 662 | |
| 663 | Netdata’s Docker image supports **health checks** via standard Docker interfaces. You can control them using the `NETDATA_HEALTHCHECK_TARGET` environment variable: |
| 664 | |
| 665 | - **Unset** – Defaults to checking `/api/v1/info`. |
| 666 | - **`cli`** – Uses `netdatacli ping` to confirm the Agent is running (but not full data collection). |
| 667 | |
| 668 | The default `/api/v1/info` check is usually sufficient. However, if the web server is disabled or API access is restricted, you'll need to customize the health check configuration. |
| 669 | |
| 670 | ## Publish a test image to your own repository |
| 671 | |
| 672 | At Netdata, we provide multiple ways of testing your Docker images using your own repositories. |
| 673 | |
| 674 | :::tip |
| 675 | |
| 676 | You may either use the command line tools available or take advantage of our GitHub Actions infrastructure. |
| 677 | |
| 678 | ::: |