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
Joel Hans committed
May 7, 2020 at 09:55 UTC
95a5f93640d6ffed96f59f70f955402e481597bf
1 file changed
+60
-29
packaging/docker/README.md
+60
-29
@@ -1,23 +1,32 @@
1
<!--
2
---
3
title: "Install Netdata with Docker"
4
+date: 2020-04-23
5
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/docker/README.md
6
---
7
-->
8
8
-# Install Netdata with Docker
9
+# Install the Netdata Agent with Docker
10
10
-Running Netdata in a container works best for an internal network or to quickly analyze a host. Docker helps you get set
11
-up quickly, and doesn't install anything permanent on the system, which makes uninstalling Netdata easy.
11
+Running the Netdata Agent in a container works best for an internal network or to quickly analyze a host. Docker helps
12
+you get set up quickly, and doesn't install anything permanent on the system, which makes uninstalling the Agent easy.
13
14
See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
15
15
-## Limitations running Netdata in Docker
16
+Starting with v1.12, Netdata collects anonymous usage information by default and sends it to Google Analytics. Read
17
+about the information collected, and learn how to-opt, on our [anonymous statistics](/docs/anonymous-statistics.md)
18
+page.
19
+
20
+The usage statistics are _vital_ for us, as we use them to discover bugs and priortize new features. We thank you for
21
+_actively_ contributing to Netdata's future.
22
+
23
+## Limitations running the Agent in Docker
24
17
-For monitoring the whole host, running Netdata in a container can limit its capabilities. Some data, like the host OS
18
-performance or status, is not accessible or not as detailed in a container as when running Netdata directly on the host.
25
+For monitoring the whole host, running the Agent in a container can limit its capabilities. Some data, like the host OS
26
+performance or status, is not accessible or not as detailed in a container as when running the Agent directly on the
27
+host.
28
20
-A way around this is to provide special mounts to the Docker container so that Netdata can get visibility on host OS
29
+A way around this is to provide special mounts to the Docker container so that the Agent can get visibility on host OS
30
information like `/sys` and `/proc` folders or even `/etc/group` and shadow files.
31
32
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
40
increased security, you can enable rescrambling of Netdata packages during runtime by setting the environment variable
41
`RESCRAMBLE=true` while starting Netdata with a Docker container.
42
34
-## Run Netdata with the docker command
43
+## Run the Agent with the Docker command
44
36
-Quickly start Netdata with the `docker` command. Netdata is then available at `http://host:19999`.
45
+Quickly start a new Agent with the `docker run` command.
46
47
```bash
48
docker run -d --name=netdata \
49
-p 19999:19999 \
50
+ -v netdatalib:/var/lib/netdata \
51
+ -v netdatacache:/var/cache/netdata \
52
-v /etc/passwd:/host/etc/passwd:ro \
53
-v /etc/group:/host/etc/group:ro \
54
-v /proc:/host/proc:ro \
55
-v /sys:/host/sys:ro \
56
-v /etc/os-release:/host/etc/os-release:ro \
57
+ --restart unless-stopped \
58
--cap-add SYS_PTRACE \
59
--security-opt apparmor=unconfined \
60
netdata/netdata
61
```
62
51
-The above can be converted to a `docker-compose.yml` file for ease of management:
63
+You can then access the dashboard at `http://localhost:19999`.
64
+
65
+## Run the Agent with Docker Compose
66
+
67
+The above can be converted to a `docker-compose.yml` file to use with [Docker
68
+Compose](https://docs.docker.com/compose/):
69
70
```yaml
71
version: '3'
72
services:
73
netdata:
74
image: netdata/netdata
75
+ container_name: netdata
76
hostname: example.com # set to fqdn of host
77
ports:
78
- 19999:19999
79
+ restart: unless-stopped
80
cap_add:
81
- SYS_PTRACE
82
security_opt:
83
- apparmor:unconfined
84
volumes:
85
+ - netdatalib:/var/lib/netdata
86
+ - netdatacache:/var/cache/netdata
87
- /etc/passwd:/host/etc/passwd:ro
88
- /etc/group:/host/etc/group:ro
89
- /proc:/host/proc:ro
90
- /sys:/host/sys:ro
91
+ - /etc/os-release:/host/etc/os-release:ro
92
+
93
+volumes:
94
+ netdatalib:
95
+ netdatacache:
96
```
97
72
-Some of the bind-mounts are optional depending on how you use Netdata:
98
+Run `docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
99
74
-* If you don't want to use the apps.plugin functionality, you can remove the mounts of `/etc/passwd` and `/etc/group`
75
- (they are used to get proper user and group names for the monitored host) to get slightly better security.
100
+## Configure Agent containers
101
77
-* Most modern linux distros supply `/etc/os-release` although some older distros only supply `/etc/lsb-release`. If
78
- this is the case you can change the line above that mounts the file inside the container to
79
- `-v /etc/lsb-release:/host/etc/lsb-release:ro`.
102
+You may need to configure the above `docker run...` and `docker-compose` commands based on your needs. You should
103
+reference the [`docker run`](https://docs.docker.com/engine/reference/run/) and [Docker
104
+Compose](https://docs.docker.com/compose/) documentation for details, but we'll cover a few recommended configurations
105
+below, as well as those that are unique to Netdata Agent containers.
106
81
-* If your host is virtualized then Netdata cannot detect it from inside the container and will output the wrong
82
- metadata (e.g. on `/api/v1/info` queries). You can fix this by setting a variable that overrides the detection
83
- using, e.g. `--env VIRTUALIZATION=$(systemd-detect-virt -v)`. If you are using a `docker-compose.yml` then add:
84
-```
107
+### Add or remove other volumes
108
+
109
+Some of the volumes are optional depending on how you use Netdata:
110
+
111
+- If you don't want to use the apps.plugin functionality, you can remove the mounts of `/etc/passwd` and `/etc/group`
112
+ (they are used to get proper user and group names for the monitored host) to get slightly better security.
113
+- Most modern linux distros supply `/etc/os-release` although some older distros only supply `/etc/lsb-release`. If
114
+ this is the case you can change the line above that mounts the file inside the container to
115
+ `-v /etc/lsb-release:/host/etc/lsb-release:ro`.
116
+- If your host is virtualized then Netdata cannot detect it from inside the container and will output the wrong
117
+ metadata (e.g. on `/api/v1/info` queries). You can fix this by setting a variable that overrides the detection
118
+ using, e.g. `--env VIRTUALIZATION=$(systemd-detect-virt -v)`. If you are using a `docker-compose.yml` then add:
119
+
120
+```yaml
121
environment:
122
- VIRTUALIZATION=${VIRTUALIZATION}
123
```
124
+
125
This allows the information to be passed into `docker-compose` using:
89
-```
126
+
127
+```bash
128
VIRTUALIZATION=$(systemd-detect-virt -v) docker-compose up
129
```
130
93
-Starting with v1.12, Netdata collects anonymous usage information by default and sends it to Google Analytics. Read
94
-about the information collected, and learn how to-opt, on our [anonymous statistics](/docs/anonymous-statistics.md)
95
-page.
96
-
97
-The usage statistics are _vital_ for us, as we use them to discover bugs and priortize new features. We thank you for
98
-_actively_ contributing to Netdata's future.
99
-
131
### Docker container names resolution
132
133
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
209
[Netdata daemon command line options](https://docs.netdata.cloud/daemon/#command-line-options) such as the IP address
210
Netdata will be running on, using the [command instruction](https://docs.docker.com/engine/reference/builder/#cmd).
211
181
-## Install Netdata using docker-compose with SSL/TLS enabled HTTP Proxy
212
+## Install the Agent using Docker Compose with SSL/TLS enabled HTTP Proxy
213
214
For a permanent installation on a public server, you should [secure the Netdata
215
instance](/docs/netdata-security.md). This section contains an example of how to install Netdata with an SSL