diff options
author | Joel Hans <joel@netdata.cloud> | 2020-05-07 09:55:34 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-05-07 09:55:34 -0700 |
commit | 95a5f93640d6ffed96f59f70f955402e481597bf (patch) | |
tree | cdc9a6f78406266dd2e45b7246c52a49af3a3abb /packaging | |
parent | 79b78d4d0a308aa19d0eb1d72c0b71ef870eb423 (diff) |
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
Diffstat (limited to 'packaging')
-rw-r--r-- | packaging/docker/README.md | 89 |
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 |