diff options
Diffstat (limited to 'packaging/docker/README.md')
| -rw-r--r-- | packaging/docker/README.md | 625 |
1 files changed, 275 insertions, 350 deletions
diff --git a/packaging/docker/README.md b/packaging/docker/README.md index ef7dd6de7..eb7deb203 100644 --- a/packaging/docker/README.md +++ b/packaging/docker/README.md @@ -12,43 +12,58 @@ import TabItem from '@theme/TabItem'; # Install Netdata with Docker -## Limitations running the Agent in Docker +## Create a new Netdata Agent container -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. +You can create a new Agent container using either `docker run` or `docker-compose`. After using any method, you can +visit the Agent dashboard `http://NODE:19999`. -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. +The Netdata container requires different privileges and mounts to provide functionality similar to that provided by +Netdata installed on the host. Below you can find a list of Netdata components that need these privileges and mounts, +along with their descriptions. -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). +<details> +<summary>Privileges</summary> -Our POWER8+ Docker images do not support our FreeIPMI collector. This is a technical limitation in FreeIPMI itself, -and unfortunately not something we can realistically work around. +| Component | Privileges | Description | +|:---------------:|:-----------------------------:|--------------------------------------------------------------------------------------------------------------------------| +| cgroups.plugin | host PID mode, SYS_ADMIN | Container network interfaces monitoring. Map virtual interfaces in the system namespace to interfaces inside containers. | +| proc.plugin | host network mode | Host system networking stack monitoring. | +| go.d.plugin | host network mode | Monitoring applications running on the host and inside containers. | +| local-listeners | host network mode, SYS_PTRACE | Discovering local services/applications. Map open (listening) ports to running services/applications. | -## Create a new Netdata Agent container +</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`. +<details> +<summary>Mounts</summary> + +| Component | Mounts | Description | +|:--------------:|:--------------------------:|-------------------------------------------------------------------------------------------------------------------------------------| +| netdata | /etc/os-release | Host info detection. | +| cgroups.plugin | /sys, /var/run/docker.sock | Docker containers monitoring and name resolution. | +| 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. | +| apps.plugin | /etc/passwd, /etc/group | Monitoring of host system resource usage by each user and user group. | +| proc.plugin | /proc | Host system monitoring (CPU, memory, network interfaces, disks, etc.). | + +</details> -Both methods create a [bind mount](https://docs.docker.com/storage/bind-mounts/) for Netdata's configuration files -_within the container_ at `/etc/netdata`. See the [configuration section](#configure-agent-containers) for details. If -you want to access the configuration files from your _host_ machine, see [host-editable -configuration](#host-editable-configuration). +### Recommended way + +Both methods create a [volume](https://docs.docker.com/storage/volumes/) for Netdata's configuration files +_within the container_ at `/etc/netdata`. +See the [configure section](#configure-agent-containers) for details. If you want to access the configuration files from +your _host_ machine, see [host-editable configuration](#with-host-editable-configuration). <Tabs> <TabItem value="docker_run" label="docker run"> <h3> Using the <code>docker run</code> command </h3> -Run the following command along with the following options on your terminal, to start a new container. +Run the following command in your terminal to start a new container. ```bash docker run -d --name=netdata \ - -p 19999:19999 \ + --pid=host \ + --network=host \ -v netdataconfig:/etc/netdata \ -v netdatalib:/var/lib/netdata \ -v netdatacache:/var/cache/netdata \ @@ -57,159 +72,82 @@ docker run -d --name=netdata \ -v /proc:/host/proc:ro \ -v /sys:/host/sys:ro \ -v /etc/os-release:/host/etc/os-release:ro \ + -v /var/run/docker.sock:/var/run/docker.sock:ro \ --restart unless-stopped \ --cap-add SYS_PTRACE \ + --cap-add SYS_ADMIN \ --security-opt apparmor=unconfined \ netdata/netdata ``` -> ### Note -> -> 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. - </TabItem> <TabItem value="docker compose" label="docker-compose"> <h3> Using the <code>docker-compose</code> command</h3> -#### Steps - -1. Copy the following code and paste into a new file called `docker-compose.yml` - - ```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: - - netdataconfig:/etc/netdata - - 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: - netdataconfig: - netdatalib: - netdatacache: - ``` - -2. Run `docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container. +Create a file named `docker-compose.yml` in your project directory and paste the code below. From your project +directory, start Netdata by running `docker-compose up -d`. -> :bookmark_tabs: Note -> -> 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. +```yaml +version: '3' +services: + netdata: + image: netdata/netdata + container_name: netdata + pid: host + network_mode: host + restart: unless-stopped + cap_add: + - SYS_PTRACE + - SYS_ADMIN + security_opt: + - apparmor:unconfined + volumes: + - netdataconfig:/etc/netdata + - 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 + - /var/run/docker.sock:/var/run/docker.sock:ro + +volumes: + netdataconfig: + netdatalib: + netdatacache: +``` </TabItem> </Tabs> -## Docker tags - -See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata). - -The official `netdata/netdata` Docker image provides the following named tags: - -* `stable`: The `stable` tag will always point to the most recently published stable build. -* `edge`: The `edge` tag will always point ot the most recently published nightly build. In most cases, this is - updated daily at around 01:00 UTC. -* `latest`: The `latest` tag will always point to 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. - -Additionally, for each stable release, three tags are pushed, one with the full version of the release (for example, -`v1.30.0`), one with just the major and minor version (for example, `v1.30`), and one with just the major version -(for example, `v1`). The tags for the minor versions and major versions are updated whenever a release is published -that would match that tag (for example, if `v1.30.1` were to be published, the `v1.30` tag would be updated to -point to that instead of `v1.30.0`). - -## Adding extra packages at runtime - -By default, the official Netdata container images do not include a number of optional runtime dependencies. You -can add these dependencies, or any other APK packages, at runtime by listing them in the environment variable -`NETDATA_EXTRA_APK_PACKAGES`. - -Commonly useful packages include: - -- `apcupsd`: For monitoring APC UPS devices. -- `libvirt-daemon`: For resolving cgroup names for libvirt domains. -- `lm-sensors`: For monitoring hardware sensors. -- `msmtp`: For email alert support. -- `netcat-openbsd`: For IRC alert support. - -## Health Checks - -Our Docker image provides integrated support for health checks through the standard Docker interfaces. +> :bookmark_tabs: Note +> +> 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. -You can control how the health checks run by using the environment variable `NETDATA_HEALTHCHECK_TARGET` as follows: +### With host-editable configuration -- If left unset, the health check will attempt to access the - `/api/v1/info` endpoint of the agent. -- If set to the exact value 'cli', the health check - script will use `netdatacli ping` to determine if the agent is running - correctly or not. This is sufficient to ensure that Netdata did not - hang during startup, but does not provide a rigorous verification - that the daemon is collecting data or is otherwise usable. -- 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 cases, this should - start with `http://localhost:19999/` to check the agent running in - the container. - -In most cases, the default behavior of checking the `/api/v1/info` -endpoint will be sufficient. If you are using a configuration which -disables the web server or restricts access to certain APIs, you will -need to use a non-default configuration for health checks to work. +Use a [bind mount](https://docs.docker.com/storage/bind-mounts/) for `/etc/netdata` rather than a volume. -## Configure Agent containers - -If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), and you -want to edit Netdata's configuration, you must first use `docker exec` to attach to the container. Replace `netdata` -with the name of your container. +This example assumes that you have created `netdataconfig/` in your home directory. ```bash -docker exec -it netdata bash -cd /etc/netdata -./edit-config netdata.conf +mkdir netdataconfig ``` -You need to restart the Agent to apply changes. Exit the container if you haven't already, then use the `docker` command -to restart the container: `docker restart netdata`. - -### Host-editable configuration - -> :warning: Warning -> -> 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 -> the host system. - -If you want to make your container's configuration directory accessible from the host system, you need to use a -[volume](https://docs.docker.com/storage/bind-mounts/) rather than a bind mount. The following commands create a -temporary `netdata_tmp` container, which is used to populate a `netdataconfig` directory, which is then mounted inside -the container at `/etc/netdata`. +<Tabs> +<TabItem value="docker_run" label="docker run"> -```bash -mkdir netdataconfig -docker run -d --name netdata_tmp netdata/netdata -docker cp netdata_tmp:/etc/netdata netdataconfig/ -docker rm -f netdata_tmp -``` +<h3> Using the <code>docker run</code> command </h3> -**`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 \` line from the recommended example above. +Run the following command in your terminal to start a new container. ```bash docker run -d --name=netdata \ - -p 19999:19999 \ + --pid=host \ + --network=host \ -v $(pwd)/netdataconfig/netdata:/etc/netdata \ -v netdatalib:/var/lib/netdata \ -v netdatacache:/var/cache/netdata \ @@ -218,15 +156,21 @@ docker run -d --name=netdata \ -v /proc:/host/proc:ro \ -v /sys:/host/sys:ro \ -v /etc/os-release:/host/etc/os-release:ro \ + -v /var/run/docker.sock:/var/run/docker.sock:ro \ --restart unless-stopped \ --cap-add SYS_PTRACE \ + --cap-add SYS_ADMIN \ --security-opt apparmor=unconfined \ netdata/netdata ``` -**Docker Compose**: Copy the following code and paste into a new file called `docker-compose.yml`, then run -`docker-compose up -d` in the same directory as the `docker-compose.yml` file to start the container. Note the changed -`./netdataconfig/netdata:/etc/netdata:ro` line from the recommended example above. +</TabItem> +<TabItem value="docker compose" label="docker-compose"> + +<h3> Using the <code>docker-compose</code> command</h3> + +Create a file named `docker-compose.yml` in your project directory and paste the code below. From your project +directory, start Netdata by running `docker-compose up -d`. ```yaml version: '3' @@ -234,12 +178,12 @@ services: netdata: image: netdata/netdata container_name: netdata - hostname: example.com # set to fqdn of host - ports: - - 19999:19999 + pid: host + network_mode: host restart: unless-stopped cap_add: - SYS_PTRACE + - SYS_ADMIN security_opt: - apparmor:unconfined volumes: @@ -251,131 +195,172 @@ services: - /proc:/host/proc:ro - /sys:/host/sys:ro - /etc/os-release:/host/etc/os-release:ro + - /var/run/docker.sock:/var/run/docker.sock:ro volumes: netdatalib: netdatacache: ``` -### Change the default hostname +</TabItem> +</Tabs> -You can change the hostname of a Docker container, and thus the name that appears in the local dashboard and in Netdata -Cloud, when creating a new container. If you want to change the hostname of a Netdata container _after_ you started it, -you can safely stop and remove it. Your configuration and metrics data reside in persistent volumes and are reattached to -the recreated container. +### With SSL/TLS enabled HTTP Proxy -If you use `docker-run`, use the `--hostname` option with `docker run`. +For a permanent installation on a public server, you +should [secure the Netdata 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. -```bash -docker run -d --name=netdata \ - --hostname=my_docker_netdata +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. + +#### Caddyfile + +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. + +```caddyfile +netdata.example.org { + reverse_proxy netdata:19999 + tls admin@example.org +} ``` -If you use `docker-compose`, add a `hostname:` key/value pair into your `docker-compose.yml` file, then create the -container again using `docker-compose up -d`. +#### docker-compose.yml + +After setting Caddyfile run this with `docker-compose up -d` to have a fully functioning Netdata setup behind an HTTP reverse +proxy. ```yaml version: '3' services: + caddy: + image: caddy:2 + ports: + - "80:80" + - "443:443" + volumes: + - /opt/Caddyfile:/etc/caddy/Caddyfile + - caddy_data:/data + - caddy_config:/config netdata: image: netdata/netdata container_name: netdata - hostname: my_docker_compose_netdata - ... -``` - -If you don't want to destroy and recreate your container, you can edit the Agent's `netdata.conf` file directly. See the -above section on [configuring Agent containers](#configure-agent-containers) to find the appropriate method based on -how you created the container. - -Alternatively, you can directly use the hostname from the node running the container by mounting -`/etc/hostname` from the host in the container. With `docker run`, this can be done by adding `--volume -/etc/hostname:/etc/hostname:ro` to the options. If you are using Docker Compose, you can add an entry to the -container's `volumes` section reading `- /etc/hostname:/etc/hostname:ro`. - -### Add or remove other volumes - -Some 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 + hostname: example.com # set to fqdn of host + restart: always + pid: host + cap_add: + - SYS_PTRACE + - SYS_ADMIN + security_opt: + - apparmor:unconfined + volumes: + - netdataconfig:/etc/netdata + - 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 + - /var/run/docker.sock:/var/run/docker.sock:ro +volumes: + caddy_data: + caddy_config: + netdatalib: + netdatacache: ``` -#### Files inside systemd volumes - -If a volume is used by systemd service, some files can be removed during -[reinitialization](https://github.com/netdata/netdata/issues/9916). To avoid this, you need to add -`RuntimeDirectoryPreserve=yes` to the service file. +#### Restrict access with basic auth -### Docker container names resolution +You can restrict access by +following the [official caddy guide](https://caddyserver.com/docs/caddyfile/directives/basicauth#basicauth) and adding lines +to Caddyfile. -There are a few options for resolving container names within Netdata. Some methods of doing so will allow root access to -your machine from within the container. Please read the following carefully. - -#### Docker socket proxy (safest option) +### With Docker socket proxy Deploy a Docker socket proxy that accepts and filters out requests using something like [HAProxy](https://github.com/netdata/netdata/blob/master/docs/Running-behind-haproxy.md) or -[CetusGuard](https://github.com/hectorm/cetusguard) so that it restricts connections to read-only access to the `/containers` -endpoint. +[CetusGuard](https://github.com/hectorm/cetusguard) 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 network. Access to the proxy container is limited to only within the network. -Here are two examples, the first using [a Docker image based on HAProxy](https://github.com/Tecnativa/docker-socket-proxy) -and the second using [CetusGuard](https://github.com/hectorm/cetusguard). - -##### Docker Socket Proxy (HAProxy) +#### HAProxy ```yaml version: '3' services: netdata: image: netdata/netdata - # ... rest of your config ... - ports: - - 19999:19999 + container_name: netdata + pid: host + network_mode: host + restart: unless-stopped + cap_add: + - SYS_PTRACE + - SYS_ADMIN + security_opt: + - apparmor:unconfined + volumes: + - netdataconfig:/etc/netdata + - 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 environment: - - DOCKER_HOST=proxy:2375 + - DOCKER_HOST=localhost:2375 proxy: + network_mode: host image: tecnativa/docker-socket-proxy volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: - CONTAINERS=1 + +volumes: + netdataconfig: + netdatalib: + netdatacache: ``` + **Note:** Replace `2375` with the port of your proxy. -##### CetusGuard +#### CetusGuard ```yaml version: '3' services: netdata: image: netdata/netdata - # ... rest of your config ... - ports: - - 19999:19999 + container_name: netdata + pid: host + network_mode: host + restart: unless-stopped + cap_add: + - SYS_PTRACE + - SYS_ADMIN + security_opt: + - apparmor:unconfined + volumes: + - netdataconfig:/etc/netdata + - 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 environment: - - DOCKER_HOST=cetusguard:2375 + - DOCKER_HOST=localhost:2375 cetusguard: image: hectorm/cetusguard:v1 + network_mode: host read_only: true volumes: - /var/run/docker.sock:/var/run/docker.sock:ro @@ -385,86 +370,65 @@ services: CETUSGUARD_RULES: | ! Inspect a container GET %API_PREFIX_CONTAINERS%/%CONTAINER_ID_OR_NAME%/json + +volumes: + netdataconfig: + netdatalib: + netdatacache: ``` You can run the 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. -#### Giving group access to the Docker socket (less safe) - -> :warning: Caution -> -> You should seriously consider the necessity of activating this option, as it grants to the `netdata` -> user access to the privileged socket connection of docker service and therefore your whole machine. - -If you want to have your container names resolved by Netdata, make the `netdata` user be part of the group that owns the -socket. +## Docker tags -```yaml -version: '3' -services: - netdata: - image: netdata/netdata - # ... rest of your config ... - volumes: - # ... other volumes ... - - /var/run/docker.sock:/var/run/docker.sock:ro - environment: - - PGID=[GROUP NUMBER] -``` +See our full list of Docker images at [Docker Hub](https://hub.docker.com/r/netdata/netdata). -To achieve that just add environment variable `PGID=[GROUP NUMBER]` to the Netdata container, where `[GROUP NUMBER]` is -practically the group id of the group assigned to the docker socket, on your host. +The official `netdata/netdata` Docker image provides the following named tags: -This group number can be found by running the following (if socket group ownership is docker): +| Tag | Description | +|:--------:|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `stable` | the most recently published stable build. | +| `edge` | the most recently published nightly build. In most cases, this is updated daily at around 01:00 UTC. | +| `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. | +| `vX.Y.Z` | the full version of the release (for example, `v1.40.0`). | +| `vX.Y` | the major and minor version (for example, `v1.40`). | +| `vX` | just the major version (for example, `v1`). | -```bash -grep docker /etc/group | cut -d ':' -f 3 -``` +The tags for minor and major versions are updated whenever a release that matches this tag is published (for example, +if `v1.40.1` were to be published, the `v1.40` tag would be updated to it instead of pointing to `v1.40.0`). -#### Running as root (unsafe) +## Configure Agent containers -> :warning: Caution -> -> You should seriously consider the necessity of activating this option, as it grants to the `netdata` user access to -> the privileged socket connection of docker service, and therefore your whole machine. +If you started an Agent container using one of the [recommended methods](#create-a-new-netdata-agent-container), and you +want to edit Netdata's configuration, you must first use `docker exec` to attach to the container. Replace `netdata` +with the name of your container. -```yaml -version: '3' -services: - netdata: - image: netdata/netdata - # ... rest of your config ... - volumes: - # ... other volumes ... - - /var/run/docker.sock:/var/run/docker.sock:ro - environment: - - DOCKER_USR=root +```bash +docker exec -it netdata bash +cd /etc/netdata +./edit-config netdata.conf ``` -### Docker container network interfaces monitoring - -Netdata can map a virtual interface in the system namespace to an interface inside a Docker container -when using network [bridge](https://docs.docker.com/network/bridge/) driver. To do this, the Netdata container needs -additional privileges: +You need to restart the Agent to apply changes. Exit the container if you haven't already, then use the `docker` command +to restart the container: `docker restart netdata`. -- the host PID mode. This turns on sharing between container and the host operating system the PID - address space (needed to get list of PIDs from `cgroup.procs` file). +### Change the default hostname -- `SYS_ADMIN` capability (needed to execute `setns()`). +You can change the hostname of a Docker container, and thus the name that appears in the local dashboard and in Netdata +Cloud, when creating a new container. If you want to change the hostname of a Netdata container _after_ you started it, +you can safely stop and remove it. Your configuration and metrics data reside in persistent volumes and are reattached +to the recreated container. -**docker run**: +If you use `docker-run`, use the `--hostname` option with `docker run`. ```bash docker run -d --name=netdata \ - ... - --pid=host \ - --cap-add SYS_ADMIN \ - ... - netdata/netdata + --hostname=my_docker_netdata ``` -**docker compose**: +If you use `docker-compose`, add a `hostname:` key/value pair into your `docker-compose.yml` file, then create the +container again using `docker-compose up -d`. ```yaml version: '3' @@ -472,87 +436,48 @@ services: netdata: image: netdata/netdata container_name: netdata - pid: host - cap_add: - - SYS_ADMIN - ... + hostname: my_docker_compose_netdata ``` -### 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](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](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 -email address for [Let's Encrypt](https://letsencrypt.org/) before starting. +If you don't want to destroy and recreate your container, you can edit the Agent's `netdata.conf` file directly. See the +above section on [configuring Agent containers](#configure-agent-containers) to find the appropriate method based on +how you created the container. -### Caddyfile +Alternatively, you can directly use the hostname from the node running the container by mounting `/etc/hostname` from +the host in the container. With `docker run`, this can be done by adding `--volume /etc/hostname:/etc/hostname:ro` to +the options. If you are using Docker Compose, you can add an entry to the container's `volumes` section +reading `- /etc/hostname:/etc/hostname:ro`. -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. +## Adding extra packages at runtime -```caddyfile -netdata.example.org { - reverse_proxy netdata:19999 - tls admin@example.org -} -``` +By default, the official Netdata container images do not include a number of optional runtime dependencies. You +can add these dependencies, or any other APK packages, at runtime by listing them in the environment variable +`NETDATA_EXTRA_APK_PACKAGES`. -### docker-compose.yml +Commonly useful packages include: -After setting Caddyfile run this with `docker-compose up -d` to have fully functioning Netdata setup behind HTTP reverse -proxy. +- `apcupsd`: For monitoring APC UPS devices. +- `libvirt-daemon`: For resolving cgroup names for libvirt domains. +- `lm-sensors`: For monitoring hardware sensors. +- `msmtp`: For email alert support. +- `netcat-openbsd`: For IRC alert support. -```yaml -version: '3' -volumes: - caddy_data: - caddy_config: +## Health Checks -services: - caddy: - image: caddy:2 - ports: - - "80:80" - - "443:443" - volumes: - - /opt/Caddyfile:/etc/caddy/Caddyfile - - caddy_data:/data - - caddy_config:/config - netdata: - restart: always - hostname: netdata.example.org - image: netdata/netdata - 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 - - /var/run/docker.sock:/var/run/docker.sock:ro +Our Docker image provides integrated support for health checks through the standard Docker interfaces. -volumes: - netdatalib: - netdatacache: -``` +You can control how the health checks run by using the environment variable `NETDATA_HEALTHCHECK_TARGET` as follows: -### Restrict access with basic auth +- If left unset, the health check will attempt to access the `/api/v1/info` endpoint of the agent. +- If set to the exact value 'cli', the health check script will use `netdatacli ping` to determine if the agent is + running correctly or not. This is sufficient to ensure that Netdata did not hang during startup, but does not provide + a rigorous verification that the daemon is collecting data or is otherwise usable. +- 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 + cases, this should start with `http://localhost:19999/` to check the agent running in the container. -You can restrict access by following [official caddy guide](https://caddyserver.com/docs/caddyfile/directives/basicauth#basicauth) and adding lines to -Caddyfile. +In most cases, the default behavior of checking the `/api/v1/info` endpoint will be sufficient. If you are using a +configuration which disables the web server or restricts access to certain APIs, you will need to use a non-default +configuration for health checks to work. ## Publish a test image to your own repository |