Install Netdata with Docker (#6596)
* minor corrections * Correct some errors * more fixes * correct grammar * explain limitations * add code-language and rearrange analytics link * add docker-compose for socket proxy * small correction Co-Authored-By: Joel Hans <joel.g.hans@gmail.com> * second correction Co-Authored-By: Joel Hans <joel.g.hans@gmail.com> * correct grammar Co-Authored-By: Joel Hans <joel.g.hans@gmail.com> * small fix Co-Authored-By: Joel Hans <joel.g.hans@gmail.com> * more fix Co-Authored-By: Joel Hans <joel.g.hans@gmail.com> * remove prerequisites * updates and rearrangements * update install Netdata with Docker doc
Promise Akpan committed
Aug 21, 2019 at 17:14 UTC
19168464247f83c0678fe9aa5275f5fdebd5663a
1 file changed
+47
-27
packaging/docker/README.md
+47
-27
@@ -1,25 +1,26 @@
1
# Install Netdata with Docker
2
3
-> :warning: As of Sep 9th, 2018 we ship [new docker builds](https://github.com/netdata/netdata/pull/3995), running Netdata in Docker with an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, not a COMMAND directive. Please adapt your execution scripts accordingly. You can find more information about ENTRYPOINT vs COMMAND is presented by goinbigdata [here](http://goinbigdata.com/docker-run-vs-cmd-vs-entrypoint/) and by docker docs [here](https://docs.docker.com/engine/reference/builder/#understand-how-cmd-and-entrypoint-interact).
4
->
5
-> Also, the `latest` is now based on alpine, so **`alpine` is not updated any more** and `armv7hf` is now replaced with `armhf` (to comply with <https://github.com/multiarch> naming), so **`armv7hf` is not updated** either.
3
+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.
4
7
-## Limitations
5
+See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
6
9
-Running Netdata in a container for monitoring the whole host, can limit its capabilities. Some data is not accessible or not as detailed as when running Netdata on the host.
7
+## Limitations running Netdata in Docker
8
11
-## Package scrambling in runtime (x86_64 only)
9
+For monitoring the whole host, running Netdata in a container can limit its capabilities.
10
+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.
11
13
-By default on x86_64 architecture our docker images use Polymorphic Polyverse Linux package scrambling. For increased security you can enable rescrambling of packages during runtime. To do this set environment variable `RESCRAMBLE=true` while starting Netdata docker container.
12
+A way around this is to provide special mounts to the Docker container so that Netdata can get visibility on host OS information like `/sys` and `/proc` folders or even `/etc/group` and shadow files.
13
15
-For more information go to [Polyverse site](https://polyverse.io/how-it-works/)
14
+Also, we now ship Docker images using an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, not a COMMAND directive. Please adapt your execution scripts accordingly. You can find more information about ENTRYPOINT vs COMMAND in the [Docker documentation](https://docs.docker.com/engine/reference/builder/#understand-how-cmd-and-entrypoint-interact).
15
+
16
+### Package scrambling in runtime (x86_64 only)
17
+
18
+Our x86_64 Docker images use [Polymorphic Polyverse Linux package scrambling](https://polyverse.io/how-it-works/). For 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.
19
20
## Run Netdata with the docker command
21
22
Quickly start Netdata with the `docker` command. Netdata is then available at <http://host:19999>
23
21
-This is good for an internal network or to quickly analyse a host.
22
-
24
```bash
25
docker run -d --name=netdata \
26
-p 19999:19999 \
@@ -32,7 +33,7 @@ docker run -d --name=netdata \
33
netdata/netdata
34
```
35
35
-The above can be converted to docker-compose file for ease of management:
36
+The above can be converted to `docker-compose` file for ease of management:
37
38
```yaml
39
version: '3'
@@ -61,10 +62,34 @@ There are a few options for resolving container names within Netdata. Some metho
62
63
#### Docker socket proxy (safest option)
64
64
-Deploy a Docker socket proxy that accepts and filter out requests using something like [HAProxy](https://docs.netdata.cloud/docs/running-behind-haproxy/) so that it restricts connections to read-only access to the CONTAINERS endpoint.
65
+Deploy a Docker socket proxy that accepts and filters out requests using something like [HAProxy](https://docs.netdata.cloud/docs/running-behind-haproxy/) so that it restricts connections to read-only access to the CONTAINERS endpoint.
66
67
The reason it's safer to expose the socket to the proxy is because Netdata has a TCP port exposed outside the Docker network. Access to the proxy container is limited to only within the network.
68
69
+Below is [an example repository (and image)](https://github.com/Tecnativa/docker-socket-proxy) that provides a proxy to the socket.
70
+
71
+You run the Docker 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.
72
+
73
+```yaml
74
+version: '3'
75
+services:
76
+ netdata:
77
+ image: netdata/netdata
78
+ # ... rest of your config ...
79
+ ports:
80
+ - 19999:19999
81
+ environment:
82
+ - DOCKER_HOST=proxy:2375
83
+ proxy:
84
+ image: tecnativa/docker-socket-proxy
85
+ volumes:
86
+ - /var/run/docker.sock:/var/run/docker.sock:ro
87
+ environment:
88
+ - CONTAINERS=1
89
+
90
+```
91
+**Note:** Replace `2375` with the port of your proxy.
92
+
93
#### Giving group access to the Docker socket (less safe)
94
95
**Important Note**: You should seriously consider the necessity of activating this option,
@@ -103,21 +128,15 @@ services:
128
129
Since we use an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, you can provide [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).
130
106
-## Install Netdata using Docker Compose with SSL/TLS enabled http proxy
107
-
108
-For a permanent installation on a public server, you should [secure your Netdata instance](../../docs/netdata-security.md). This section contains an example of how to install Netdata with an SSL reverse proxy and basic authentication.
131
+## Install Netdata using Docker Compose with SSL/TLS enabled HTTP Proxy
132
110
-You can use use the following docker-compose.yml and Caddyfile files to run Netdata with docker. Replace the Domains and email address for [Letsencrypt](https://letsencrypt.org/) before starting.
133
+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 reverse proxy and basic authentication.
134
112
-### Prerequisites
113
-
114
-- [Docker](https://docs.docker.com/install/#server)
115
-- [Docker Compose](https://docs.docker.com/compose/install/)
116
-- Domain configured in DNS pointing to host.
135
+You can use the following `docker-compose.yml` and Caddyfile files to run Netdata with Docker. Replace the domains and email address for [Let's Encrypt](https://letsencrypt.org/) before starting.
136
137
### Caddyfile
138
120
-This file needs to be placed in /opt with name `Caddyfile`. Here you customize your domain and you need to provide your email address to obtain a Letsencrypt certificate. Certificate renewal will happen automatically and will be executed internally by the caddy server.
139
+This file needs to be placed in `/opt` with name `Caddyfile`. Here you customize your domain and you need to provide your email address to obtain a Let's Encrypt certificate. Certificate renewal will happen automatically and will be executed internally by the caddy server.
140
141
```caddyfile
142
netdata.example.org {
@@ -166,8 +185,6 @@ services:
185
186
You can restrict access by following [official caddy guide](https://caddyserver.com/docs/basicauth) and adding lines to Caddyfile.
187
169
-[](<>)
170
-
188
## Publish a test image to your own repository
189
190
At Netdata, we provide multiple ways of testing your Docker images using your own repositories.
@@ -177,7 +194,7 @@ You may either use the command line tools available or take advantage of our Tra
194
195
The script `packaging/docker/build-test.sh` can be used to create an image and upload it to a repository of your choosing.
196
180
-```
197
+```bash
198
Usage: packaging/docker/build-test.sh -r <REPOSITORY> -v <VERSION> -u <DOCKER_USERNAME> -p <DOCKER_PWD> [-s]
199
-s skip build, just push the image
200
Builds an amd64 image and pushes it to the docker hub repository REPOSITORY
@@ -189,7 +206,7 @@ Example:
206
207
We get a local copy of the Helm chart at <https://github.com/netdata/helmchart>. We modify `values.yaml` to have the following:
208
192
-```
209
+```yaml
210
image:
211
repository: cakrit/netdata-prs
212
tag: PR5576
@@ -198,7 +215,7 @@ image:
215
216
We check out PR5576 and run the following:
217
201
-```
218
+```bash
219
./packaging/docker/build-test.sh -r cakrit/netdata-prs -v PR5576 -u cakrit -p 'XXX'
220
```
221
@@ -209,6 +226,7 @@ If we make changes to the code, we execute the same `build-test.sh` command, fol
226
### Inside Netdata organization, using Travis CI
227
228
To enable Travis CI integration on your own repositories (Docker and Github), you need to be part of the Netdata organization.
229
+
230
Once you have contacted the Netdata owners to setup you up on Github and Travis, execute the following steps
231
232
- Preparation
@@ -229,3 +247,5 @@ Once you have contacted the Netdata owners to setup you up on Github and Travis,
247
- COVERITY_SCAN_SUBMIT_EMAIL and COVERITY_SCAN_TOKEN variables to enable Travis to submit your code for analysis to Coverity.
248
249
Having followed these instructions, your forked repository should be all set up for Travis Integration, happy testing!
250
+
251
+[](<>)