Add persistent configuration details to Docker docs (#9926)
* Add new config details * Add bind mount to README * Add config to compose file
Joel Hans committed
Sep 16, 2020 at 06:45 UTC
09127f1e9f9f236ba4d957706f307c5f8ac1d2b2
2 files changed
+95
-14
README.md
+1
@@ -157,6 +157,7 @@ To try Netdata in a Docker container, run this:
157
```sh
158
docker run -d --name=netdata \
159
-p 19999:19999 \
160
+ -v netdataconfig:/etc/netdata \
161
-v netdatalib:/var/lib/netdata \
162
-v netdatacache:/var/cache/netdata \
163
-v /etc/passwd:/host/etc/passwd:ro \
packaging/docker/README.md
+94
-14
@@ -32,13 +32,22 @@ directive, not a COMMAND directive. Please adapt your execution scripts accordin
32
ENTRYPOINT vs COMMAND in the [Docker
33
documentation](https://docs.docker.com/engine/reference/builder/#understand-how-cmd-and-entrypoint-interact).
34
35
-## Run the Agent with the Docker command
35
+## Create a new Netdata Agent container
36
37
-Quickly start a new Agent with the `docker run` command.
37
+You can create a new Agent container using either `docker run` or Docker Compose. After using either method, you can
38
+visit the Agent dashboard `http://NODE:19999`.
39
+
40
+Both methods create a [bind mount](https://docs.docker.com/storage/bind-mounts/) for Netdata's configuration files
41
+_within the container_ at `/etc/netdata`. See the [configuration section](#configure-agent-containers) for details. If
42
+you want to access the configuration files from your _host_ machine, see [host-editable
43
+configuration](#host-editable-configuration).
44
+
45
+**`docker run`**: Use the `docker run` command, along with the following options, to start a new container.
46
47
```bash
48
docker run -d --name=netdata \
49
-p 19999:19999 \
50
+ -v netdataconfig:/etc/netdata \
51
-v netdatalib:/var/lib/netdata \
52
-v netdatacache:/var/cache/netdata \
53
-v /etc/passwd:/host/etc/passwd:ro \
@@ -52,12 +61,8 @@ docker run -d --name=netdata \
61
netdata/netdata
62
```
63
55
-You can then access the dashboard at `http://localhost:19999`.
56
-
57
-## Run the Agent with Docker Compose
58
-
59
-The above can be converted to a `docker-compose.yml` file to use with [Docker
60
-Compose](https://docs.docker.com/compose/):
64
+**Docker Compose**: Copy the following code and paste into a new file called `docker-compose.yml`, then run
65
+`docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
66
67
```yaml
68
version: '3'
@@ -74,6 +79,7 @@ services:
79
security_opt:
80
- apparmor:unconfined
81
volumes:
82
+ - netdataconfig:/etc/netdata
83
- netdatalib:/var/lib/netdata
84
- netdatacache:/var/cache/netdata
85
- /etc/passwd:/host/etc/passwd:ro
@@ -83,12 +89,11 @@ services:
89
- /etc/os-release:/host/etc/os-release:ro
90
91
volumes:
92
+ netdataconfig:
93
netdatalib:
94
netdatacache:
95
```
96
90
-Run `docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container.
91
-
97
## Health Checks
98
99
Our Docker image provides integrated support for health checks through the standard Docker interfaces.
@@ -114,10 +119,85 @@ need to use a non-default configuration for health checks to work.
119
120
## Configure Agent containers
121
117
-You may need to configure the above `docker run...` and `docker-compose` commands based on your needs. You should
118
-reference the [`docker run`](https://docs.docker.com/engine/reference/run/) and [Docker
119
-Compose](https://docs.docker.com/compose/) documentation for details, but we'll cover a few recommended configurations
120
-below, as well as those that are unique to Netdata Agent containers.
122
+If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), you
123
+must first use `docker exec` to attach to the container. Replace `netdata` with the name of your Agent container in the
124
+first command below.
125
+
126
+```bash
127
+docker exec -it netdata bash
128
+cd /etc/netdata
129
+./edit-config netdata.conf
130
+```
131
+
132
+You need to restart the Agent to apply changes. Exit the container if you haven't already, then use the `docker` command
133
+to restart the container: `docker restart netdata`.
134
+
135
+### Host-editable configuration
136
+
137
+If you want to make your container's configuration directory accessible from the host system, you need to use a
138
+[volume](https://docs.docker.com/storage/bind-mounts/) rather than a bind mount. The following commands create a
139
+temporary `netdata_tmp` container, which is used to populate a `netdataconfig` directory, which is then mounted inside
140
+the container at `/etc/netdata`.
141
+
142
+```bash
143
+mkdir netdataconfig
144
+docker run -d --name netdata_tmp netdata/netdata
145
+docker cp netdata_tmp:/etc/netdata netdataconfig/
146
+docker rm -f netdata_tmp
147
+```
148
+
149
+**`docker run`**: Use the `docker run` command, along with the following options, to start a new container. Note the
150
+changed `-v $(pwd)/netdataconfig/netdata:/etc/netdata:ro \` line from the recommended example above.
151
+
152
+```bash
153
+docker run -d --name=netdata \
154
+ -p 19999:19999 \
155
+ -v $(pwd)/netdataconfig/netdata:/etc/netdata:ro \
156
+ -v netdatalib:/var/lib/netdata \
157
+ -v netdatacache:/var/cache/netdata \
158
+ -v /etc/passwd:/host/etc/passwd:ro \
159
+ -v /etc/group:/host/etc/group:ro \
160
+ -v /proc:/host/proc:ro \
161
+ -v /sys:/host/sys:ro \
162
+ -v /etc/os-release:/host/etc/os-release:ro \
163
+ --restart unless-stopped \
164
+ --cap-add SYS_PTRACE \
165
+ --security-opt apparmor=unconfined \
166
+ netdata/netdata
167
+```
168
+
169
+**Docker Compose**: Copy the following code and paste into a new file called `docker-compose.yml`, then run
170
+`docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container. Note the changed
171
+`./netdataconfig/netdata:/etc/netdata:ro` line from the recommended example above.
172
+
173
+```yaml
174
+version: '3'
175
+services:
176
+ netdata:
177
+ image: netdata/netdata
178
+ container_name: netdata
179
+ hostname: example.com # set to fqdn of host
180
+ ports:
181
+ - 19999:19999
182
+ restart: unless-stopped
183
+ cap_add:
184
+ - SYS_PTRACE
185
+ security_opt:
186
+ - apparmor:unconfined
187
+ volumes:
188
+ - ./netdataconfig/netdata:/etc/netdata:ro
189
+ - netdatalib:/var/lib/netdata
190
+ - netdatacache:/var/cache/netdata
191
+ - /etc/passwd:/host/etc/passwd:ro
192
+ - /etc/group:/host/etc/group:ro
193
+ - /proc:/host/proc:ro
194
+ - /sys:/host/sys:ro
195
+ - /etc/os-release:/host/etc/os-release:ro
196
+
197
+volumes:
198
+ netdatalib:
199
+ netdatacache:
200
+```
201
202
### Add or remove other volumes
203