docs: add Docker container update instructions (#22311)
* docs: add Docker container update instructions Add a new 'Updating your Docker container' section to the Docker README with step-by-step instructions for both docker run and docker-compose workflows, including guidance on persistent volumes, image tags, and third-party management platforms. Add a Docker (OCI) collapsible section to UPDATE.md under Update Methods by Platform and an oci entry to the Quick Reference table, both linking to the Docker README for full details. * docs: improve Docker container update section placement and content Move update section after Docker tags, add persistent volumes admonition, version check command, critical update notification note, and third-party platform note per plan guidance. --------- Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com>
nedi-app[bot] committed
Apr 29, 2026 at 09:34 UTC
88c516da52a3c2b4b6c3cfd22c778b874020cfec
2 files changed
+74
packaging/docker/README.md
+63
@@ -535,6 +535,69 @@ The official `netdata/netdata` Docker image provides the following named tags:
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.
packaging/installer/UPDATE.md
+11
@@ -137,6 +137,16 @@ If you installed Netdata with any optional parameters, such as `--install-prefix
137
<br/>
138
</details>
139
140
+<details>
141
+<summary><strong>Docker (OCI)</strong></summary><br/>
142
+
143
+Docker-based installations are updated by pulling a new image and recreating the container. Persistent volumes preserve your configuration and metrics data across updates.
144
+
145
+For detailed instructions, see [Update your Netdata Docker container](/packaging/docker/README.md#update-your-netdata-docker-container).
146
+
147
+<br/>
148
+</details>
149
+
150
## Additional Configuration
151
152
### Control runtime behavior of the updater script
@@ -166,4 +176,5 @@ This configuration file can be edited using our [`edit-config` script](/docs/net
176
| **custom** | System package manager | Use your system's package manager |
177
| **macOS (Homebrew)** | Homebrew | `brew upgrade netdata` |
178
| **Manual Git** | Git + installer | See [manual installation steps](#update-methods-by-platform) |
179
+| **Docker (OCI)** | Image pull + recreate | See [Docker update instructions](/packaging/docker/README.md#update-your-netdata-docker-container) |
180
| **Windows** | MSI installer | Download and run latest installer |