diff options
Diffstat (limited to 'packaging/docker/README.md')
| -rw-r--r-- | packaging/docker/README.md | 93 |
1 files changed, 40 insertions, 53 deletions
diff --git a/packaging/docker/README.md b/packaging/docker/README.md index d00262a1b..aec5723e3 100644 --- a/packaging/docker/README.md +++ b/packaging/docker/README.md @@ -1,7 +1,11 @@ <!-- title: "Install Netdata with Docker" -date: 2020-04-23 -custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/docker/README.md +date: "2020-04-23" +custom_edit_url: "https://github.com/netdata/netdata/edit/master/packaging/docker/README.md" +sidebar_label: "Install Netdata with Docker" +learn_status: "Published" +learn_topic_type: "Tasks" +learn_rel_path: "Installation" --> # Install the Netdata Agent with Docker @@ -12,7 +16,7 @@ you get set up quickly, and doesn't install anything permanent on the system, wh See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata). Starting with v1.30, Netdata collects anonymous usage information by default and sends it to a self-hosted PostHog instance within the Netdata infrastructure. Read -about the information collected, and learn how to-opt, on our [anonymous statistics](/docs/anonymous-statistics.md) +about the information collected, and learn how to-opt, on our [anonymous statistics](https://github.com/netdata/netdata/blob/master/docs/anonymous-statistics.md) page. The usage statistics are _vital_ for us, as we use them to discover bugs and prioritize new features. We thank you for @@ -37,6 +41,21 @@ and unfortunately not something we can realistically work around. ## Create a new Netdata Agent container +> **Notice**: all `docker run` commands and `docker-compose` configurations explicitly set the `nofile` limit. This is +> required on some distros until [14177](https://github.com/netdata/netdata/issues/14177) is resolved. Failure to do so +> may cause a task running in a container to hang and consume 100% of the CPU core. + +<details> +<summary>What are these "some distros"?</summary> + +If `LimitNOFILE=infinity` results in an open file limit of 1073741816: + +```bash +[fedora37 ~]$ docker run --rm busybox grep open /proc/self/limits +Max open files 1073741816 1073741816 files +``` +</details> + You can create a new Agent container using either `docker run` or Docker Compose. After using either method, you can visit the Agent dashboard `http://NODE:19999`. @@ -61,6 +80,7 @@ docker run -d --name=netdata \ --restart unless-stopped \ --cap-add SYS_PTRACE \ --security-opt apparmor=unconfined \ + --ulimit nofile=4096 \ netdata/netdata ``` @@ -81,6 +101,9 @@ services: - SYS_PTRACE security_opt: - apparmor:unconfined + ulimits: + nofile: + soft: 4096 volumes: - netdataconfig:/etc/netdata - netdatalib:/var/lib/netdata @@ -153,7 +176,7 @@ to restart the container: `docker restart netdata`. ### Host-editable configuration -> **Warning**: [edit-config](/docs/configure/nodes.md#the-netdata-config-directory) script doesn't work when executed on +> **Warning**: [edit-config](https://github.com/netdata/netdata/blob/master/docs/configure/nodes.md#the-netdata-config-directory) script doesn't work when executed on > the host system. If you want to make your container's configuration directory accessible from the host system, you need to use a @@ -169,12 +192,12 @@ docker rm -f netdata_tmp ``` **`docker run`**: Use the `docker run` command, along with the following options, to start a new container. Note the -changed `-v $(pwd)/netdataconfig/netdata:/etc/netdata:ro \` line from the recommended example above. +changed `-v $(pwd)/netdataconfig/netdata:/etc/netdata \` line from the recommended example above. ```bash docker run -d --name=netdata \ -p 19999:19999 \ - -v $(pwd)/netdataconfig/netdata:/etc/netdata:ro \ + -v $(pwd)/netdataconfig/netdata:/etc/netdata \ -v netdatalib:/var/lib/netdata \ -v netdatacache:/var/cache/netdata \ -v /etc/passwd:/host/etc/passwd:ro \ @@ -185,6 +208,7 @@ docker run -d --name=netdata \ --restart unless-stopped \ --cap-add SYS_PTRACE \ --security-opt apparmor=unconfined \ + --ulimit nofile=4096 \ netdata/netdata ``` @@ -206,6 +230,9 @@ services: - SYS_PTRACE security_opt: - apparmor:unconfined + ulimits: + nofile: + soft: 4096 volumes: - ./netdataconfig/netdata:/etc/netdata:ro - netdatalib:/var/lib/netdata @@ -295,7 +322,7 @@ your machine from within the container. Please read the following carefully. #### Docker socket proxy (safest option) Deploy a Docker socket proxy that accepts and filters out requests using something like -[HAProxy](/docs/Running-behind-haproxy.md) so that it restricts connections to read-only access to the CONTAINERS +[HAProxy](https://github.com/netdata/netdata/blob/master/docs/Running-behind-haproxy.md) so that it restricts connections to read-only access to the CONTAINERS endpoint. The reason it's safer to expose the socket to the proxy is because Netdata has a TCP port exposed outside the Docker @@ -414,13 +441,13 @@ services: ### Pass command line options to Netdata Since we use an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, you can provide -[Netdata daemon command line options](/daemon/README.md#command-line-options) such as the IP address Netdata will be +[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 running on, using the [command instruction](https://docs.docker.com/engine/reference/builder/#cmd). ## 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 +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 reverse proxy and basic authentication. You can use the following `docker-compose.yml` and Caddyfile files to run Netdata with Docker. Replace the domains and @@ -468,6 +495,9 @@ services: - SYS_PTRACE security_opt: - apparmor:unconfined + ulimits: + nofile: + soft: 4096 volumes: - netdatalib:/var/lib/netdata - netdatacache:/var/cache/netdata @@ -490,47 +520,4 @@ Caddyfile. ## Publish a test image to your own repository At Netdata, we provide multiple ways of testing your Docker images using your own repositories. -You may either use the command line tools available or take advantage of our Travis CI infrastructure. - -### Inside Netdata organization, using Travis CI - -To enable Travis CI integration on your own repositories (Docker and GitHub), you need to be part of the Netdata -organization. - -Once you have contacted the Netdata owners to setup you up on GitHub and Travis, execute the following steps - -- Preparation - - Have Netdata forked on your personal GitHub account - - Get a GitHub token: Go to **GitHub settings** -> **Developer Settings** -> **Personal access tokens**, and - generate a new token with full access to `repo_hook`, read-only access to `admin:org`, `public_repo`, - `repo_deployment`, `repo:status`, and `user:email` settings enabled. This will be your `GITHUB_TOKEN` that is - described later in the instructions, so keep it somewhere safe. - - Contact the Netdata team and seek for permissions on `https://scan.coverity.com` should you require Travis to be - able to push your forked code to coverity for analysis and report. Once you are setup, you should have your - email you used in coverity and a token from them. These will be your `COVERITY_SCAN_SUBMIT_EMAIL` and - `COVERITY_SCAN_TOKEN` that we will refer to later. - - Have a valid Docker hub account, the credentials from this account will be your `DOCKER_USERNAME` and - `DOCKER_PWD` mentioned later. - -- Setting up Travis CI for your own fork (Detailed instructions provided by Travis team [here](https://docs.travis-ci.com/user/tutorial/)) - - Login to travis with your own GITHUB credentials (There is Open Auth access) - - Go to your profile settings, under [repositories](https://travis-ci.com/account/repositories) section and setup - your Netdata fork to be built by Travis CI. - - Once the repository has been setup, go to repository settings within Travis CI (usually under - `https://travis-ci.com/NETDATA_DEVELOPER/netdata/settings`, where `NETDATA_DEVELOPER` is your GitHub handle), - and select your desired settings. - -- While in Travis settings, under Netdata repository settings in the Environment Variables section, you need to add - the following: - - `DOCKER_USERNAME` and `DOCKER_PWD` variables so that Travis can log in to your Docker Hub account and publish - Docker images there. - - `REPOSITORY` variable to `NETDATA_DEVELOPER/netdata`, where `NETDATA_DEVELOPER` is your GitHub handle again. - - `GITHUB_TOKEN` variable with the token generated on the preparation step, for Travis workflows to function - properly. - - `COVERITY_SCAN_SUBMIT_EMAIL` and `COVERITY_SCAN_TOKEN` variables to enable Travis to submit your code for - analysis to Coverity. - -Having followed these instructions, your forked repository should be all set up for integration with Travis CI. Happy -testing! - - +You may either use the command line tools available or take advantage of our GitHub Acions infrastructure. |