docs: make the default Docker installation provide the full feature set (#15339)
Co-authored-by: Fotis Voutsas <fotis@netdata.cloud>
Ilya Mashchenko committed
Jul 11, 2023 at 16:12 UTC
7fba677e7806567ac78f95c8a1b57015e7676492
2 files changed
+275
-350
collectors/freeipmi.plugin/README.md
+1
-1
@@ -67,7 +67,7 @@ Metrics:
67
68
### sensor
69
70
-These metrics refer to the VPN user.
70
+These metrics refer to the sensor.
71
72
Labels:
73
packaging/docker/README.md
+274
-349
@@ -12,43 +12,58 @@ import TabItem from '@theme/TabItem';
12
13
# Install Netdata with Docker
14
15
-## Limitations running the Agent in Docker
15
+## Create a new Netdata Agent container
16
17
-For monitoring the whole host, running the Agent 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 the Agent directly on the
19
-host.
17
+You can create a new Agent container using either `docker run` or `docker-compose`. After using any method, you can
18
+visit the Agent dashboard `http://NODE:19999`.
19
21
-A way around this is to provide special mounts to the Docker container so that the Agent can get visibility on host OS
22
-information like `/sys` and `/proc` folders or even `/etc/group` and shadow files.
20
+The Netdata container requires different privileges and mounts to provide functionality similar to that provided by
21
+Netdata installed on the host. Below you can find a list of Netdata components that need these privileges and mounts,
22
+along with their descriptions.
23
24
-Also, we now ship Docker images using an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)
25
-directive, not a COMMAND directive. Please adapt your execution scripts accordingly. You can find more information about
26
-ENTRYPOINT vs COMMAND in the [Docker
27
-documentation](https://docs.docker.com/engine/reference/builder/#understand-how-cmd-and-entrypoint-interact).
24
+<details>
25
+<summary>Privileges</summary>
26
29
-Our POWER8+ Docker images do not support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself,
30
-and unfortunately not something we can realistically work around.
27
+| Component | Privileges | Description |
28
+|:---------------:|:-----------------------------:|--------------------------------------------------------------------------------------------------------------------------|
29
+| cgroups.plugin | host PID mode, SYS_ADMIN | Container network interfaces monitoring. Map virtual interfaces in the system namespace to interfaces inside containers. |
30
+| proc.plugin | host network mode | Host system networking stack monitoring. |
31
+| go.d.plugin | host network mode | Monitoring applications running on the host and inside containers. |
32
+| local-listeners | host network mode, SYS_PTRACE | Discovering local services/applications. Map open (listening) ports to running services/applications. |
33
32
-## Create a new Netdata Agent container
34
+</details>
35
34
-You can create a new Agent container using either `docker run` or `docker-compose`. After using either method, you can
35
-visit the Agent dashboard `http://NODE:19999`.
36
+<details>
37
+<summary>Mounts</summary>
38
+
39
+| Component | Mounts | Description |
40
+|:--------------:|:--------------------------:|-------------------------------------------------------------------------------------------------------------------------------------|
41
+| netdata | /etc/os-release | Host info detection. |
42
+| cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. |
43
+| 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) collector. |
44
+| apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. |
45
+| proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). |
46
+
47
+</details>
48
+
49
+### Recommended way
50
51
Both methods create a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files
38
-_within the container_ at `/etc/netdata`. See the [configuration section](#configure-agent-containers) for details. If
39
-you want to access the configuration files from your _host_ machine, see [host-editable
40
-configuration](#host-editable-configuration).
52
+_within the container_ at `/etc/netdata`.
53
+See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from
54
+your _host_ machine, see [host-editable configuration](#with-host-editable-configuration).
55
56
<Tabs>
57
<TabItem value="docker_run" label="docker run">
58
59
<h3> Using the <code>docker run</code> command </h3>
60
47
-Run the following command along with the following options on your terminal, to start a new container.
61
+Run the following command in your terminal to start a new container.
62
63
```bash
64
docker run -d --name=netdata \
51
- -p 19999:19999 \
65
+ --pid=host \
66
+ --network=host \
67
-v netdataconfig:/etc/netdata \
68
-v netdatalib:/var/lib/netdata \
69
-v netdatacache:/var/cache/netdata \
@@ -57,159 +72,82 @@ docker run -d --name=netdata \
72
-v /proc:/host/proc:ro \
73
-v /sys:/host/sys:ro \
74
-v /etc/os-release:/host/etc/os-release:ro \
75
+ -v /var/run/docker.sock:/var/run/docker.sock:ro \
76
--restart unless-stopped \
77
--cap-add SYS_PTRACE \
78
+ --cap-add SYS_ADMIN \
79
--security-opt apparmor=unconfined \
80
netdata/netdata
81
```
82
66
-> ### Note
67
->
68
-> If you plan to Claim 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 tab.
69
-
83
</TabItem>
84
<TabItem value="docker compose" label="docker-compose">
85
86
<h3> Using the <code>docker-compose</code> command</h3>
87
75
-#### Steps
76
-
77
-1. Copy the following code and paste into a new file called `docker-compose.yml`
78
-
79
- ```yaml
80
- version: '3'
81
- services:
82
- netdata:
83
- image: netdata/netdata
84
- container_name: netdata
85
- hostname: example.com # set to fqdn of host
86
- ports:
87
- - 19999:19999
88
- restart: unless-stopped
89
- cap_add:
90
- - SYS_PTRACE
91
- security_opt:
92
- - apparmor:unconfined
93
- volumes:
94
- - netdataconfig:/etc/netdata
95
- - netdatalib:/var/lib/netdata
96
- - netdatacache:/var/cache/netdata
97
- - /etc/passwd:/host/etc/passwd:ro
98
- - /etc/group:/host/etc/group:ro
99
- - /proc:/host/proc:ro
100
- - /sys:/host/sys:ro
101
- - /etc/os-release:/host/etc/os-release:ro
102
-
103
- volumes:
104
- netdataconfig:
105
- netdatalib:
106
- netdatacache:
107
- ```
108
-
109
-2. Run `docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
88
+Create a file named `docker-compose.yml` in your project directory and paste the code below. From your project
89
+directory, start Netdata by running `docker-compose up -d`.
90
111
-> :bookmark_tabs: Note
112
->
113
-> If you plan to Claim 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.
91
+```yaml
92
+version: '3'
93
+services:
94
+ netdata:
95
+ image: netdata/netdata
96
+ container_name: netdata
97
+ pid: host
98
+ network_mode: host
99
+ restart: unless-stopped
100
+ cap_add:
101
+ - SYS_PTRACE
102
+ - SYS_ADMIN
103
+ security_opt:
104
+ - apparmor:unconfined
105
+ volumes:
106
+ - netdataconfig:/etc/netdata
107
+ - netdatalib:/var/lib/netdata
108
+ - netdatacache:/var/cache/netdata
109
+ - /etc/passwd:/host/etc/passwd:ro
110
+ - /etc/group:/host/etc/group:ro
111
+ - /proc:/host/proc:ro
112
+ - /sys:/host/sys:ro
113
+ - /etc/os-release:/host/etc/os-release:ro
114
+ - /var/run/docker.sock:/var/run/docker.sock:ro
115
+
116
+volumes:
117
+ netdataconfig:
118
+ netdatalib:
119
+ netdatacache:
120
+```
121
122
</TabItem>
123
</Tabs>
124
118
-## Docker tags
119
-
120
-See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
121
-
122
-The official `netdata/netdata` Docker image provides the following named tags:
123
-
124
-* `stable`: The `stable` tag will always point to the most recently published stable build.
125
-* `edge`: The `edge` tag will always point ot the most recently published nightly build. In most cases, this is
126
- updated daily at around 01:00 UTC.
127
-* `latest`: The `latest` tag will always point to the most recently published build, whether it’s a stable build
128
- or a nightly build. This is what Docker will use by default if you do not specify a tag.
129
-
130
-Additionally, for each stable release, three tags are pushed, one with the full version of the release (for example,
131
-`v1.30.0`), one with just the major and minor version (for example, `v1.30`), and one with just the major version
132
-(for example, `v1`). The tags for the minor versions and major versions are updated whenever a release is published
133
-that would match that tag (for example, if `v1.30.1` were to be published, the `v1.30` tag would be updated to
134
-point to that instead of `v1.30.0`).
135
-
136
-## Adding extra packages at runtime
137
-
138
-By default, the official Netdata container images do not include a number of optional runtime dependencies. You
139
-can add these dependencies, or any other APK packages, at runtime by listing them in the environment variable
140
-`NETDATA_EXTRA_APK_PACKAGES`.
141
-
142
-Commonly useful packages include:
143
-
144
-- `apcupsd`: For monitoring APC UPS devices.
145
-- `libvirt-daemon`: For resolving cgroup names for libvirt domains.
146
-- `lm-sensors`: For monitoring hardware sensors.
147
-- `msmtp`: For email alert support.
148
-- `netcat-openbsd`: For IRC alert support.
149
-
150
-## Health Checks
151
-
152
-Our Docker image provides integrated support for health checks through the standard Docker interfaces.
125
+> :bookmark_tabs: Note
126
+>
127
+> If you plan to Claim the node to Netdata Cloud, you can find the command with the right parameters by clicking the "
128
+> Add Nodes" button in your Space's "Nodes" view.
129
154
-You can control how the health checks run by using the environment variable `NETDATA_HEALTHCHECK_TARGET` as follows:
130
+### With host-editable configuration
131
156
-- If left unset, the health check will attempt to access the
157
- `/api/v1/info` endpoint of the agent.
158
-- If set to the exact value 'cli', the health check
159
- script will use `netdatacli ping` to determine if the agent is running
160
- correctly or not. This is sufficient to ensure that Netdata did not
161
- hang during startup, but does not provide a rigorous verification
162
- that the daemon is collecting data or is otherwise usable.
163
-- If set to anything else, the health check will treat the value as a
164
- URL to check for a 200 status code on. In most cases, this should
165
- start with `http://localhost:19999/` to check the agent running in
166
- the container.
167
-
168
-In most cases, the default behavior of checking the `/api/v1/info`
169
-endpoint will be sufficient. If you are using a configuration which
170
-disables the web server or restricts access to certain APIs, you will
171
-need to use a non-default configuration for health checks to work.
132
+Use a [bind mount](https://docs.docker.com/storage/bind-mounts/) for `/etc/netdata` rather than a volume.
133
173
-## Configure Agent containers
174
-
175
-If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), and you
176
-want to edit Netdata's configuration, you must first use `docker exec` to attach to the container. Replace `netdata`
177
-with the name of your container.
134
+This example assumes that you have created `netdataconfig/` in your home directory.
135
136
```bash
180
-docker exec -it netdata bash
181
-cd /etc/netdata
182
-./edit-config netdata.conf
137
+mkdir netdataconfig
138
```
139
185
-You need to restart the Agent to apply changes. Exit the container if you haven't already, then use the `docker` command
186
-to restart the container: `docker restart netdata`.
187
-
188
-### Host-editable configuration
189
-
190
-> :warning: Warning
191
->
192
-> The [edit-config](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) script doesn't work when executed on
193
-> the host system.
194
-
195
-If you want to make your container's configuration directory accessible from the host system, you need to use a
196
-[bind mount](https://docs.docker.com/storage/bind-mounts/) rather than a volume. The following commands create a
197
-temporary `netdata_tmp` container, which is used to populate a `netdataconfig` directory, which is then mounted inside
198
-the container at `/etc/netdata`.
140
+<Tabs>
141
+<TabItem value="docker_run" label="docker run">
142
200
-```bash
201
-mkdir netdataconfig
202
-docker run -d --name netdata_tmp netdata/netdata
203
-docker cp netdata_tmp:/etc/netdata netdataconfig/
204
-docker rm -f netdata_tmp
205
-```
143
+<h3> Using the <code>docker run</code> command </h3>
144
207
-**`docker run`**: Use the `docker run` command, along with the following options, to start a new container. Note the
208
-changed `-v $(pwd)/netdataconfig/netdata:/etc/netdata \` line from the recommended example above.
145
+Run the following command in your terminal to start a new container.
146
147
```bash
148
docker run -d --name=netdata \
212
- -p 19999:19999 \
149
+ --pid=host \
150
+ --network=host \
151
-v $(pwd)/netdataconfig/netdata:/etc/netdata \
152
-v netdatalib:/var/lib/netdata \
153
-v netdatacache:/var/cache/netdata \
@@ -218,15 +156,21 @@ docker run -d --name=netdata \
156
-v /proc:/host/proc:ro \
157
-v /sys:/host/sys:ro \
158
-v /etc/os-release:/host/etc/os-release:ro \
159
+ -v /var/run/docker.sock:/var/run/docker.sock:ro \
160
--restart unless-stopped \
161
--cap-add SYS_PTRACE \
162
+ --cap-add SYS_ADMIN \
163
--security-opt apparmor=unconfined \
164
netdata/netdata
165
```
166
227
-**Docker Compose**: Copy the following code and paste into a new file called `docker-compose.yml`, then run
228
-`docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container. Note the changed
229
-`./netdataconfig/netdata:/etc/netdata:ro` line from the recommended example above.
167
+</TabItem>
168
+<TabItem value="docker compose" label="docker-compose">
169
+
170
+<h3> Using the <code>docker-compose</code> command</h3>
171
+
172
+Create a file named `docker-compose.yml` in your project directory and paste the code below. From your project
173
+directory, start Netdata by running `docker-compose up -d`.
174
175
```yaml
176
version: '3'
@@ -234,12 +178,12 @@ services:
178
netdata:
179
image: netdata/netdata
180
container_name: netdata
237
- hostname: example.com # set to fqdn of host
238
- ports:
239
- - 19999:19999
181
+ pid: host
182
+ network_mode: host
183
restart: unless-stopped
184
cap_add:
185
- SYS_PTRACE
186
+ - SYS_ADMIN
187
security_opt:
188
- apparmor:unconfined
189
volumes:
@@ -251,131 +195,172 @@ services:
195
- /proc:/host/proc:ro
196
- /sys:/host/sys:ro
197
- /etc/os-release:/host/etc/os-release:ro
198
+ - /var/run/docker.sock:/var/run/docker.sock:ro
199
200
volumes:
201
netdatalib:
202
netdatacache:
203
```
204
260
-### Change the default hostname
205
+</TabItem>
206
+</Tabs>
207
262
-You can change the hostname of a Docker container, and thus the name that appears in the local dashboard and in Netdata
263
-Cloud, when creating a new container. If you want to change the hostname of a Netdata container _after_ you started it,
264
-you can safely stop and remove it. Your configuration and metrics data reside in persistent volumes and are reattached to
265
-the recreated container.
208
+### With SSL/TLS enabled HTTP Proxy
209
267
-If you use `docker-run`, use the `--hostname` option with `docker run`.
210
+For a permanent installation on a public server, you
211
+should [secure the Netdata instance](https://github.com/netdata/netdata/blob/master/docs/netdata-security.md). This
212
+section contains an example of how to install Netdata with an SSL reverse proxy and basic authentication.
213
269
-```bash
270
-docker run -d --name=netdata \
271
- --hostname=my_docker_netdata
214
+You can use the following `docker-compose.yml` and Caddyfile files to run Netdata with Docker. Replace the domains and
215
+email address for [Let's Encrypt](https://letsencrypt.org/) before starting.
216
+
217
+#### Caddyfile
218
+
219
+This file needs to be placed in `/opt` with name `Caddyfile`. Here you customize your domain, and you need to provide
220
+your email address to obtain a Let's Encrypt certificate. Certificate renewal will happen automatically and will be
221
+executed internally by the caddy server.
222
+
223
+```caddyfile
224
+netdata.example.org {
225
+ reverse_proxy netdata:19999
226
+ tls admin@example.org
227
+}
228
```
229
274
-If you use `docker-compose`, add a `hostname:` key/value pair into your `docker-compose.yml` file, then create the
275
-container again using `docker-compose up -d`.
230
+#### docker-compose.yml
231
+
232
+After setting Caddyfile run this with `docker-compose up -d` to have a fully functioning Netdata setup behind an HTTP reverse
233
+proxy.
234
235
```yaml
236
version: '3'
237
services:
238
+ caddy:
239
+ image: caddy:2
240
+ ports:
241
+ - "80:80"
242
+ - "443:443"
243
+ volumes:
244
+ - /opt/Caddyfile:/etc/caddy/Caddyfile
245
+ - caddy_data:/data
246
+ - caddy_config:/config
247
netdata:
248
image: netdata/netdata
249
container_name: netdata
283
- hostname: my_docker_compose_netdata
284
- ...
285
-```
286
-
287
-If you don't want to destroy and recreate your container, you can edit the Agent's `netdata.conf` file directly. See the
288
-above section on [configuring Agent containers](#configure-agent-containers) to find the appropriate method based on
289
-how you created the container.
290
-
291
-Alternatively, you can directly use the hostname from the node running the container by mounting
292
-`/etc/hostname` from the host in the container. With `docker run`, this can be done by adding `--volume
293
-/etc/hostname:/etc/hostname:ro` to the options. If you are using Docker Compose, you can add an entry to the
294
-container's `volumes` section reading `- /etc/hostname:/etc/hostname:ro`.
295
-
296
-### Add or remove other volumes
297
-
298
-Some volumes are optional depending on how you use Netdata:
299
-
300
-- If you don't want to use the apps.plugin functionality, you can remove the mounts of `/etc/passwd` and `/etc/group`
301
- (they are used to get proper user and group names for the monitored host) to get slightly better security.
302
-- Most modern linux distros supply `/etc/os-release` although some older distros only supply `/etc/lsb-release`. If
303
- this is the case you can change the line above that mounts the file inside the container to
304
- `-v /etc/lsb-release:/host/etc/lsb-release:ro`.
305
-- If your host is virtualized then Netdata cannot detect it from inside the container and will output the wrong
306
- metadata (e.g. on `/api/v1/info` queries). You can fix this by setting a variable that overrides the detection
307
- using, e.g. `--env VIRTUALIZATION=$(systemd-detect-virt -v)`. If you are using a `docker-compose.yml` then add:
308
-
309
-```yaml
310
- environment:
311
- - VIRTUALIZATION=${VIRTUALIZATION}
312
-```
313
-
314
-This allows the information to be passed into `docker-compose` using:
315
-
316
-```bash
317
-VIRTUALIZATION=$(systemd-detect-virt -v) docker-compose up
250
+ hostname: example.com # set to fqdn of host
251
+ restart: always
252
+ pid: host
253
+ cap_add:
254
+ - SYS_PTRACE
255
+ - SYS_ADMIN
256
+ security_opt:
257
+ - apparmor:unconfined
258
+ volumes:
259
+ - netdataconfig:/etc/netdata
260
+ - netdatalib:/var/lib/netdata
261
+ - netdatacache:/var/cache/netdata
262
+ - /etc/passwd:/host/etc/passwd:ro
263
+ - /etc/group:/host/etc/group:ro
264
+ - /proc:/host/proc:ro
265
+ - /sys:/host/sys:ro
266
+ - /etc/os-release:/host/etc/os-release:ro
267
+ - /var/run/docker.sock:/var/run/docker.sock:ro
268
+volumes:
269
+ caddy_data:
270
+ caddy_config:
271
+ netdatalib:
272
+ netdatacache:
273
```
274
320
-#### Files inside systemd volumes
321
-
322
-If a volume is used by systemd service, some files can be removed during
323
-[reinitialization](https://github.com/netdata/netdata/issues/9916). To avoid this, you need to add
324
-`RuntimeDirectoryPreserve=yes` to the service file.
275
+#### Restrict access with basic auth
276
326
-### Docker container names resolution
277
+You can restrict access by
278
+following the [official caddy guide](https://caddyserver.com/docs/caddyfile/directives/basicauth#basicauth) and adding lines
279
+to Caddyfile.
280
328
-There are a few options for resolving container names within Netdata. Some methods of doing so will allow root access to
329
-your machine from within the container. Please read the following carefully.
330
-
331
-#### Docker socket proxy (safest option)
281
+### With Docker socket proxy
282
283
Deploy a Docker socket proxy that accepts and filters out requests using something like
284
[HAProxy](https://github.com/netdata/netdata/blob/master/docs/Running-behind-haproxy.md) or
335
-[CetusGuard](https://github.com/hectorm/cetusguard) so that it restricts connections to read-only access to the `/containers`
336
-endpoint.
285
+[CetusGuard](https://github.com/hectorm/cetusguard) so that it restricts connections to read-only access to
286
+the `/containers` endpoint.
287
288
The reason it's safer to expose the socket to the proxy is because Netdata has a TCP port exposed outside the Docker
289
network. Access to the proxy container is limited to only within the network.
290
341
-Here are two examples, the first using [a Docker image based on HAProxy](https://github.com/Tecnativa/docker-socket-proxy)
342
-and the second using [CetusGuard](https://github.com/hectorm/cetusguard).
343
-
344
-##### Docker Socket Proxy (HAProxy)
291
+#### HAProxy
292
293
```yaml
294
version: '3'
295
services:
296
netdata:
297
image: netdata/netdata
351
- # ... rest of your config ...
352
- ports:
353
- - 19999:19999
298
+ container_name: netdata
299
+ pid: host
300
+ network_mode: host
301
+ restart: unless-stopped
302
+ cap_add:
303
+ - SYS_PTRACE
304
+ - SYS_ADMIN
305
+ security_opt:
306
+ - apparmor:unconfined
307
+ volumes:
308
+ - netdataconfig:/etc/netdata
309
+ - netdatalib:/var/lib/netdata
310
+ - netdatacache:/var/cache/netdata
311
+ - /etc/passwd:/host/etc/passwd:ro
312
+ - /etc/group:/host/etc/group:ro
313
+ - /proc:/host/proc:ro
314
+ - /sys:/host/sys:ro
315
+ - /etc/os-release:/host/etc/os-release:ro
316
environment:
355
- - DOCKER_HOST=proxy:2375
317
+ - DOCKER_HOST=localhost:2375
318
proxy:
319
+ network_mode: host
320
image: tecnativa/docker-socket-proxy
321
volumes:
322
- /var/run/docker.sock:/var/run/docker.sock:ro
323
environment:
324
- CONTAINERS=1
325
+
326
+volumes:
327
+ netdataconfig:
328
+ netdatalib:
329
+ netdatacache:
330
```
331
+
332
**Note:** Replace `2375` with the port of your proxy.
333
365
-##### CetusGuard
334
+#### CetusGuard
335
336
```yaml
337
version: '3'
338
services:
339
netdata:
340
image: netdata/netdata
372
- # ... rest of your config ...
373
- ports:
374
- - 19999:19999
341
+ container_name: netdata
342
+ pid: host
343
+ network_mode: host
344
+ restart: unless-stopped
345
+ cap_add:
346
+ - SYS_PTRACE
347
+ - SYS_ADMIN
348
+ security_opt:
349
+ - apparmor:unconfined
350
+ volumes:
351
+ - netdataconfig:/etc/netdata
352
+ - netdatalib:/var/lib/netdata
353
+ - netdatacache:/var/cache/netdata
354
+ - /etc/passwd:/host/etc/passwd:ro
355
+ - /etc/group:/host/etc/group:ro
356
+ - /proc:/host/proc:ro
357
+ - /sys:/host/sys:ro
358
+ - /etc/os-release:/host/etc/os-release:ro
359
environment:
376
- - DOCKER_HOST=cetusguard:2375
360
+ - DOCKER_HOST=localhost:2375
361
cetusguard:
362
image: hectorm/cetusguard:v1
363
+ network_mode: host
364
read_only: true
365
volumes:
366
- /var/run/docker.sock:/var/run/docker.sock:ro
@@ -385,86 +370,65 @@ services:
370
CETUSGUARD_RULES: |
371
! Inspect a container
372
GET %API_PREFIX_CONTAINERS%/%CONTAINER_ID_OR_NAME%/json
373
+
374
+volumes:
375
+ netdataconfig:
376
+ netdatalib:
377
+ netdatacache:
378
```
379
380
You can run the socket proxy in its own Docker Compose file and leave it on a private network that you can add to
381
other services that require access.
382
393
-#### Giving group access to the Docker socket (less safe)
394
-
395
-> :warning: Caution
396
->
397
-> You should seriously consider the necessity of activating this option, as it grants to the `netdata`
398
-> user access to the privileged socket connection of docker service and therefore your whole machine.
399
-
400
-If you want to have your container names resolved by Netdata, make the `netdata` user be part of the group that owns the
401
-socket.
383
+## Docker tags
384
403
-```yaml
404
-version: '3'
405
-services:
406
- netdata:
407
- image: netdata/netdata
408
- # ... rest of your config ...
409
- volumes:
410
- # ... other volumes ...
411
- - /var/run/docker.sock:/var/run/docker.sock:ro
412
- environment:
413
- - PGID=[GROUP NUMBER]
414
-```
385
+See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata).
386
416
-To achieve that just add environment variable `PGID=[GROUP NUMBER]` to the Netdata container, where `[GROUP NUMBER]` is
417
-practically the group id of the group assigned to the docker socket, on your host.
387
+The official `netdata/netdata` Docker image provides the following named tags:
388
419
-This group number can be found by running the following (if socket group ownership is docker):
389
+| Tag | Description |
390
+|:--------:|---------------------------------------------------------------------------------------------------------------------------------------------------------|
391
+| `stable` | the most recently published stable build. |
392
+| `edge` | the most recently published nightly build. In most cases, this is updated daily at around 01:00 UTC. |
393
+| `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. |
394
+| `vX.Y.Z` | the full version of the release (for example, `v1.40.0`). |
395
+| `vX.Y` | the major and minor version (for example, `v1.40`). |
396
+| `vX` | just the major version (for example, `v1`). |
397
421
-```bash
422
-grep docker /etc/group | cut -d ':' -f 3
423
-```
398
+The tags for minor and major versions are updated whenever a release that matches this tag is published (for example,
399
+if `v1.40.1` were to be published, the `v1.40` tag would be updated to it instead of pointing to `v1.40.0`).
400
425
-#### Running as root (unsafe)
401
+## Configure Agent containers
402
427
-> :warning: Caution
428
->
429
-> You should seriously consider the necessity of activating this option, as it grants to the `netdata` user access to
430
-> the privileged socket connection of docker service, and therefore your whole machine.
403
+If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), and you
404
+want to edit Netdata's configuration, you must first use `docker exec` to attach to the container. Replace `netdata`
405
+with the name of your container.
406
432
-```yaml
433
-version: '3'
434
-services:
435
- netdata:
436
- image: netdata/netdata
437
- # ... rest of your config ...
438
- volumes:
439
- # ... other volumes ...
440
- - /var/run/docker.sock:/var/run/docker.sock:ro
441
- environment:
442
- - DOCKER_USR=root
407
+```bash
408
+docker exec -it netdata bash
409
+cd /etc/netdata
410
+./edit-config netdata.conf
411
```
412
445
-### Docker container network interfaces monitoring
446
-
447
-Netdata can map a virtual interface in the system namespace to an interface inside a Docker container
448
-when using network [bridge](https://docs.docker.com/network/bridge/) driver. To do this, the Netdata container needs
449
-additional privileges:
413
+You need to restart the Agent to apply changes. Exit the container if you haven't already, then use the `docker` command
414
+to restart the container: `docker restart netdata`.
415
451
-- the host PID mode. This turns on sharing between container and the host operating system the PID
452
- address space (needed to get list of PIDs from `cgroup.procs` file).
416
+### Change the default hostname
417
454
-- `SYS_ADMIN` capability (needed to execute `setns()`).
418
+You can change the hostname of a Docker container, and thus the name that appears in the local dashboard and in Netdata
419
+Cloud, when creating a new container. If you want to change the hostname of a Netdata container _after_ you started it,
420
+you can safely stop and remove it. Your configuration and metrics data reside in persistent volumes and are reattached
421
+to the recreated container.
422
456
-**docker run**:
423
+If you use `docker-run`, use the `--hostname` option with `docker run`.
424
425
```bash
426
docker run -d --name=netdata \
460
- ...
461
- --pid=host \
462
- --cap-add SYS_ADMIN \
463
- ...
464
- netdata/netdata
427
+ --hostname=my_docker_netdata
428
```
429
467
-**docker compose**:
430
+If you use `docker-compose`, add a `hostname:` key/value pair into your `docker-compose.yml` file, then create the
431
+container again using `docker-compose up -d`.
432
433
```yaml
434
version: '3'
@@ -472,87 +436,48 @@ services:
436
netdata:
437
image: netdata/netdata
438
container_name: netdata
475
- pid: host
476
- cap_add:
477
- - SYS_ADMIN
478
- ...
439
+ hostname: my_docker_compose_netdata
440
```
441
481
-### Pass command line options to Netdata
482
-
483
-Since we use an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, you can provide
484
-[Netdata daemon command line options](https://github.com/netdata/netdata/blob/master/daemon/README.md#command-line-options) such as the IP address Netdata will be
485
-running on, using the [command instruction](https://docs.docker.com/engine/reference/builder/#cmd).
486
-
487
-## Install the Agent using Docker Compose with SSL/TLS enabled HTTP Proxy
488
-
489
-For a permanent installation on a public server, you should [secure the Netdata
490
-instance](https://github.com/netdata/netdata/blob/master/docs/netdata-security.md). This section contains an example of how to install Netdata with an SSL
491
-reverse proxy and basic authentication.
492
-
493
-You can use the following `docker-compose.yml` and Caddyfile files to run Netdata with Docker. Replace the domains and
494
-email address for [Let's Encrypt](https://letsencrypt.org/) before starting.
442
+If you don't want to destroy and recreate your container, you can edit the Agent's `netdata.conf` file directly. See the
443
+above section on [configuring Agent containers](#configure-agent-containers) to find the appropriate method based on
444
+how you created the container.
445
496
-### Caddyfile
446
+Alternatively, you can directly use the hostname from the node running the container by mounting `/etc/hostname` from
447
+the host in the container. With `docker run`, this can be done by adding `--volume /etc/hostname:/etc/hostname:ro` to
448
+the options. If you are using Docker Compose, you can add an entry to the container's `volumes` section
449
+reading `- /etc/hostname:/etc/hostname:ro`.
450
498
-This file needs to be placed in `/opt` with name `Caddyfile`. Here you customize your domain, and you need to provide
499
-your email address to obtain a Let's Encrypt certificate. Certificate renewal will happen automatically and will be
500
-executed internally by the caddy server.
451
+## Adding extra packages at runtime
452
502
-```caddyfile
503
-netdata.example.org {
504
- reverse_proxy netdata:19999
505
- tls admin@example.org
506
-}
507
-```
453
+By default, the official Netdata container images do not include a number of optional runtime dependencies. You
454
+can add these dependencies, or any other APK packages, at runtime by listing them in the environment variable
455
+`NETDATA_EXTRA_APK_PACKAGES`.
456
509
-### docker-compose.yml
457
+Commonly useful packages include:
458
511
-After setting Caddyfile run this with `docker-compose up -d` to have fully functioning Netdata setup behind HTTP reverse
512
-proxy.
459
+- `apcupsd`: For monitoring APC UPS devices.
460
+- `libvirt-daemon`: For resolving cgroup names for libvirt domains.
461
+- `lm-sensors`: For monitoring hardware sensors.
462
+- `msmtp`: For email alert support.
463
+- `netcat-openbsd`: For IRC alert support.
464
514
-```yaml
515
-version: '3'
516
-volumes:
517
- caddy_data:
518
- caddy_config:
465
+## Health Checks
466
520
-services:
521
- caddy:
522
- image: caddy:2
523
- ports:
524
- - "80:80"
525
- - "443:443"
526
- volumes:
527
- - /opt/Caddyfile:/etc/caddy/Caddyfile
528
- - caddy_data:/data
529
- - caddy_config:/config
530
- netdata:
531
- restart: always
532
- hostname: netdata.example.org
533
- image: netdata/netdata
534
- cap_add:
535
- - SYS_PTRACE
536
- security_opt:
537
- - apparmor:unconfined
538
- volumes:
539
- - netdatalib:/var/lib/netdata
540
- - netdatacache:/var/cache/netdata
541
- - /etc/passwd:/host/etc/passwd:ro
542
- - /etc/group:/host/etc/group:ro
543
- - /proc:/host/proc:ro
544
- - /sys:/host/sys:ro
545
- - /var/run/docker.sock:/var/run/docker.sock:ro
467
+Our Docker image provides integrated support for health checks through the standard Docker interfaces.
468
547
-volumes:
548
- netdatalib:
549
- netdatacache:
550
-```
469
+You can control how the health checks run by using the environment variable `NETDATA_HEALTHCHECK_TARGET` as follows:
470
552
-### Restrict access with basic auth
471
+- If left unset, the health check will attempt to access the `/api/v1/info` endpoint of the agent.
472
+- If set to the exact value 'cli', the health check script will use `netdatacli ping` to determine if the agent is
473
+ running correctly or not. This is sufficient to ensure that Netdata did not hang during startup, but does not provide
474
+ a rigorous verification that the daemon is collecting data or is otherwise usable.
475
+- If set to anything else, the health check will treat the value as a URL to check for a 200 status code on. In most
476
+ cases, this should start with `http://localhost:19999/` to check the agent running in the container.
477
554
-You can restrict access by following [official caddy guide](https://caddyserver.com/docs/caddyfile/directives/basicauth#basicauth) and adding lines to
555
-Caddyfile.
478
+In most cases, the default behavior of checking the `/api/v1/info` endpoint will be sufficient. If you are using a
479
+configuration which disables the web server or restricts access to certain APIs, you will need to use a non-default
480
+configuration for health checks to work.
481
482
## Publish a test image to your own repository
483