Docs: Add instructions to persist metrics and restart policy (#8813)

* Add restart policy and some cleanup

* Add persistence config

* Slightly better language

* Fix for Ilya

* Move to -v syntax

1 files changed, 60 insertions, 29 deletions

diff --git a/packaging/docker/README.md b/packaging/docker/README.md
index b594e54e88..4a0cb080b9 100644
--- a/packaging/docker/README.md
+++ b/packaging/docker/README.md
@@ -1,23 +1,32 @@
 <!--
 ---
 title: "Install Netdata with Docker"
+date: 2020-04-23
 custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/docker/README.md
 ---
 -->
 
-# Install Netdata with Docker
+# Install the Netdata Agent with Docker
 
-Running Netdata in a container works best for an internal network or to quickly analyze a host. Docker helps you get set
-up quickly, and doesn't install anything permanent on the system, which makes uninstalling Netdata easy.
+Running the Netdata Agent in a container works best for an internal network or to quickly analyze a host. Docker helps
+you get set up quickly, and doesn't install anything permanent on the system, which makes uninstalling the Agent easy.
 
 See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
 
-## Limitations running Netdata in Docker
+Starting with v1.12, Netdata collects anonymous usage information by default and sends it to Google Analytics. Read
+about the information collected, and learn how to-opt, on our [anonymous statistics](/docs/anonymous-statistics.md)
+page.
+
+The usage statistics are _vital_ for us, as we use them to discover bugs and priortize new features. We thank you for
+_actively_ contributing to Netdata's future.
+
+## Limitations running the Agent in Docker
 
-For monitoring the whole host, running Netdata in a container can limit its capabilities. Some data, like the host OS
-performance or status, is not accessible or not as detailed in a container as when running Netdata directly on the host.
+For monitoring the whole host, running the Agent in a container can limit its capabilities. Some data, like the host OS
+performance or status, is not accessible or not as detailed in a container as when running the Agent directly on the
+host.
 
-A way around this is to provide special mounts to the Docker container so that Netdata can get visibility on host OS
+A way around this is to provide special mounts to the Docker container so that the Agent can get visibility on host OS
 information like `/sys` and `/proc` folders or even `/etc/group` and shadow files.
 
 Also, we now ship Docker images using an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)
@@ -31,72 +40,94 @@ Our x86_64 Docker images use [Polymorphic Polyverse Linux package scrambling](ht
 increased security, you can enable rescrambling of Netdata packages during runtime by setting the environment variable
 `RESCRAMBLE=true` while starting Netdata with a Docker container.
 
-## Run Netdata with the docker command
+## Run the Agent with the Docker command
 
-Quickly start Netdata with the `docker` command. Netdata is then available at `http://host:19999`.
+Quickly start a new Agent with the `docker run` command.
 
 ```bash
 docker run -d --name=netdata \
   -p 19999:19999 \
+  -v netdatalib:/var/lib/netdata \
+  -v netdatacache:/var/cache/netdata \
   -v /etc/passwd:/host/etc/passwd:ro \
   -v /etc/group:/host/etc/group:ro \
   -v /proc:/host/proc:ro \
   -v /sys:/host/sys:ro \
   -v /etc/os-release:/host/etc/os-release:ro \
+  --restart unless-stopped \
   --cap-add SYS_PTRACE \
   --security-opt apparmor=unconfined \
   netdata/netdata
 ```
 
-The above can be converted to a `docker-compose.yml` file for ease of management:
+You can then access the dashboard at `http://localhost:19999`.
+
+## Run the Agent with Docker Compose
+
+The above can be converted to a `docker-compose.yml` file to use with [Docker
+Compose](https://docs.docker.com/compose/):
 
 ```yaml
 version: '3'
 services:
   netdata:
     image: netdata/netdata
+    container_name: netdata
     hostname: example.com # set to fqdn of host
     ports:
       - 19999:19999
+    restart: unless-stopped
     cap_add:
       - SYS_PTRACE
     security_opt:
       - apparmor:unconfined
     volumes:
+      - netdatalib:/var/lib/netdata
+      - netdatacache:/var/cache/netdata
       - /etc/passwd:/host/etc/passwd:ro
       - /etc/group:/host/etc/group:ro
       - /proc:/host/proc:ro
       - /sys:/host/sys:ro
+      - /etc/os-release:/host/etc/os-release:ro
+
+volumes:
+  netdatalib:
+  netdatacache:
 ```
 
-Some of the bind-mounts are optional depending on how you use Netdata:
+Run `docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
 
-* If you don't want to use the apps.plugin functionality, you can remove the mounts of `/etc/passwd` and `/etc/group`
-  (they are used to get proper user and group names for the monitored host) to get slightly better security.
+## Configure Agent containers
 
-* Most modern linux distros supply `/etc/os-release` although some older distros only supply `/etc/lsb-release`. If
-  this is the case you can change the line above that mounts the file inside the container to
-  `-v /etc/lsb-release:/host/etc/lsb-release:ro`.
+You may need to configure the above `docker run...` and `docker-compose` commands based on your needs. You should
+reference the [`docker run`](https://docs.docker.com/engine/reference/run/) and [Docker
+Compose](https://docs.docker.com/compose/) documentation for details, but we'll cover a few recommended configurations
+below, as well as those that are unique to Netdata Agent containers.
 
-* If your host is virtualized then Netdata cannot detect it from inside the container and will output the wrong
-  metadata (e.g. on `/api/v1/info` queries). You can fix this by setting a variable that overrides the detection
-  using, e.g. `--env VIRTUALIZATION=$(systemd-detect-virt -v)`. If you are using a `docker-compose.yml` then add:
-```
+### Add or remove other volumes
+
+Some of the volumes are optional depending on how you use Netdata:
+
+-   If you don't want to use the apps.plugin functionality, you can remove the mounts of `/etc/passwd` and `/etc/group`
+    (they are used to get proper user and group names for the monitored host) to get slightly better security.
+-   Most modern linux distros supply `/etc/os-release` although some older distros only supply `/etc/lsb-release`. If
+    this is the case you can change the line above that mounts the file inside the container to
+    `-v /etc/lsb-release:/host/etc/lsb-release:ro`.
+-   If your host is virtualized then Netdata cannot detect it from inside the container and will output the wrong
+    metadata (e.g. on `/api/v1/info` queries). You can fix this by setting a variable that overrides the detection
+    using, e.g. `--env VIRTUALIZATION=$(systemd-detect-virt -v)`. If you are using a `docker-compose.yml` then add:
+
+```yaml
     environment:
       - VIRTUALIZATION=${VIRTUALIZATION}
 ```
+
 This allows the information to be passed into `docker-compose` using:
-```
+
+```bash
 VIRTUALIZATION=$(systemd-detect-virt -v) docker-compose up
 ```
 
-Starting with v1.12, Netdata collects anonymous usage information by default and sends it to Google Analytics. Read
-about the information collected, and learn how to-opt, on our [anonymous statistics](/docs/anonymous-statistics.md)
-page.
-
-The usage statistics are _vital_ for us, as we use them to discover bugs and priortize new features. We thank you for
-_actively_ contributing to Netdata's future.
-
 ### Docker container names resolution
 
 There are a few options for resolving container names within Netdata. Some methods of doing so will allow root access to
@@ -178,7 +209,7 @@ Since we use an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#e
 [Netdata daemon command line options](https://docs.netdata.cloud/daemon/#command-line-options) such as the IP address
 Netdata will be running on, using the [command instruction](https://docs.docker.com/engine/reference/builder/#cmd). 
 
-## Install Netdata using docker-compose with SSL/TLS enabled HTTP Proxy
+## Install the Agent using Docker Compose with SSL/TLS enabled HTTP Proxy
 
 For a permanent installation on a public server, you should [secure the Netdata
 instance](/docs/netdata-security.md). This section contains an example of how to install Netdata with an SSL