{"id":15129784,"url":"https://github.com/titpetric/netdata","last_synced_at":"2025-09-28T19:31:04.722Z","repository":{"id":49929171,"uuid":"49389559","full_name":"titpetric/netdata","owner":"titpetric","description":"Dockerfile for building netdata","archived":true,"fork":false,"pushed_at":"2019-12-12T12:54:17.000Z","size":100,"stargazers_count":237,"open_issues_count":0,"forks_count":80,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-09-27T02:20:15.211Z","etag":null,"topics":["docker-container","monitoring","netdata","realtime"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/titpetric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-10T22:59:26.000Z","updated_at":"2024-09-26T06:42:28.000Z","dependencies_parsed_at":"2022-09-16T21:40:48.756Z","dependency_job_id":null,"html_url":"https://github.com/titpetric/netdata","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titpetric%2Fnetdata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titpetric%2Fnetdata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titpetric%2Fnetdata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titpetric%2Fnetdata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/titpetric","download_url":"https://codeload.github.com/titpetric/netdata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234555568,"owners_count":18851799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-container","monitoring","netdata","realtime"],"created_at":"2024-09-26T02:20:28.220Z","updated_at":"2025-09-28T19:30:59.379Z","avatar_url":"https://github.com/titpetric.png","language":"Shell","readme":"# netdata\n\nDockerfile for building and running a netdata deamon for your host instance.\n\nNetdata monitors your server with thoughts of performance and memory usage, providing detailed insight into very recent server metrics. It's nice, and now it's also dockerized.\n\nMore info about project: https://github.com/firehol/netdata\n\n\u003e **Note**: the netdata project includes telemetry. Google Analytics is used to aggregate telemetry data, with IP anonymisation turned on. There is currently\n\u003e no way to opt out, until such a mechanism can be provided at runtime instead of compile time. You can track the upstream [issue #7404](https://github.com/netdata/netdata/issues/7404) if\n\u003e you have privacy concerns. GDPR explicitly allows [processing for statistical purposes, without requiring opt-in](https://github.com/netdata/netdata/issues/7366#issuecomment-560363265) in\n\u003e it's Article 6, and related Article 89(1). Currently, you can only opt out if you build netdata without telemetry.\n\u003e\n\u003e More info about the original telemetry implementation in netdata is on [issue #4735](https://github.com/netdata/netdata/issues/4735), and instructions\n\u003e / documentation, including a way to opt out of telemetry is available here: [anonymous statistics docs page](https://docs.netdata.cloud/docs/anonymous-statistics/).\n\n# More info about me\n\nI'm primarily a full-stack web developer with strong knowledge of Docker, APIs, AWS, PHP, Go, Nginx+LUA, SQL and NoSQL databases, Video Streaming (Wowza Media Server), and handle DevOps/automation for several large scale international clients (High traffic/HA deployments).\n\nIf you need someone with this skillset, please contact me at black@scene-si.org.\n\nI'm also the author of the following books:\n\n* [Advent of Go Microservices](https://leanpub.com/go-microservices)\n* [API Foundations in Go](https://leanpub.com/api-foundations)\n* [12 Factor Applications with Docker and Go](https://leanpub.com/12fa-docker-golang)\n\nConsider buying the books to learn something new and support my open source work.\n\nFor more information, I also write a development-themed blog at [scene-si.org](https://scene-si.org/).\nI occasionally tweet my pursuits (sometimes in Slovenian) on [@TitPetric](https://twitter.com/TitPetric).\n\n# Using\n\n## Statring the container\n\n### Docker CLI\n\n```\ndocker run -d --cap-add SYS_PTRACE \\\n           -v /proc:/host/proc:ro \\\n           -v /sys:/host/sys:ro \\\n           -p 19999:19999 \\\n           --restart unless-stopped \\\n           titpetric/netdata\n```\n\n\u003e **Note:** Remove the `--restart unless-stopped` [parameter](https://docs.docker.com/config/containers/start-containers-automatically/#use-a-restart-policy) if you don't need the netdata container to start automatically on boot.\n\n### Docker Compose\n\nUse the sample [docker-compose.yml](docker-compose.yml) file.\n\n\u003e **Note:** Remove the `restart: unless-stopped` [option](https://docs.docker.com/compose/compose-file/#restart) if you don't need the netdata container to start automatically on boot.\n\n```\nmkdir netdata \u0026\u0026 cd netdata \u0026\u0026 wget https://raw.githubusercontent.com/titpetric/netdata/master/docker-compose.yml\ndocker-compose up -d\n```\n\n## Accessing the data\n\nOpen a browser on http://server:19999/ and watch how your server is doing.\n\n# Supported tags and respective Dockerfile links\n\nCheck out for [Docker Hub Tags page for titpetric/netdata](https://cloud.docker.com/repository/docker/titpetric/netdata/tags) if you\nneed to grab an older version. There's an archive of versions going back from 1.4 to the current version.\n\nThe `latest` tag is in line with the upstream and is occasionally prone to failure. As far as older tags go -\nthey will inevitably lack some new features but should provide a more stable version to run.\n\n\u003e Developers note: new tags are not added automatically which means there might be some delay between when a new\n\u003e release of netdata is available and when a new tag is available on docker hub; open an issue if that happens.\n\n# Limiting IP netdata listens to\n\nBy default netdata listens to 0.0.0.0 (any address). You might want to change this if you're running netdata in `--net=host` mode. You can pass the following environment variable:\n\n- NETDATA_IP - the IP that netdata should listen to, e.g. `127.0.0.1` for localhost only.\n\n# Passing custom netdata options\n\nIf you need to pass some custom options to netdata, you can pass the following environment variable:\n\n- NETDATA_ARGS - for example if you don't want to use NETDATA_IP above, you can pass `-e NETDATA_ARGS=\"-i 127.0.0.1\"` for same effect.\n\n# Getting emails on alarms\n\nNetdata supports forwarding alarms to an email address. You can set up msmtp by setting the following ENV variables:\n\n- SMTP_TO - This is the address alarms will be delivered to.\n- SMTP_FROM - This is the address the emails will be from. Defaults to localhost.\n- SMTP_SERVER - This is your SMTP server. Defaults to smtp.gmail.com.\n- SMTP_PORT - This is the SMTP server port. Defaults to 587.\n- SMTP_USER - This is your username for the SMTP server.\n- SMTP_PASS - This is your password for the SMTP server. Use an app password if using Gmail.\n- SMTP_TLS - Use TLS for the connection. Defaults to `on`.\n- SMTP_STARTTLS - Use STARTTLS for the connection. Defaults to `on`.\n\nFor example, using gmail:\n\n```\n-e SMTP_TO=user@gmail.com -e SMTP_USER=user -e SMTP_PASS=password\n```\n\nAlternatively, if you already have s msmtp config, you can use that config with:\n\n~~~\n-v /path/to/msmtprc:/etc/msmtprc:ro\n~~~\n\nSee the following link for details on setting up msmtp: [MSMTP - ArchWiki](https://wiki.archlinux.org/index.php/Msmtp)\n\n\u003e Note: email settings up to version v0.10.0 were different. You can get the [old documentation](https://github.com/titpetric/netdata/blob/master/releases/v0.10.0/README.md) is the corresponding release subfolder.\n\n# Adding custom alarms, charts and configuration overrides\n\nTo add custom alarms, charts or to override any default configuration file, mount a volume to the container to /etc/netdata/override, like `-v /opt/netdata/override:/etc/netdata/override:ro`.  Then, place your config files in the directory as if it was /etc/netdata/.\n\nFor example to create a custom alarm for system temperature, create a `health.d` folder in your local directory (`/opt/netdata/override` in the example above) and place a `sensors.conf` file with your alarm configuration inside the `health.d` directory.\n\n# Getting alarms in Slack\n\nNetdata supports sending alerts to slack via webhooks. You can set that up by setting the following ENV variables:\n\n- SLACK_WEBHOOK_URL - This is your incoming slack webhook\n- SLACK_CHANNEL - This is the default channel that alerts will get sent to\n\nFor example:\n\n```\n-e SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXXX -e SLACK_CHANNEL=alerts\n```\n\n# Getting alarms in Discord\n\nNetdata supports sending alerts to Discord via webhooks. You can set that up by setting the following ENV variables:\n\n- DISCORD_WEBHOOK_URL - This is your incoming Discord webhook\n- DISCORD_RECIPIENT - This is the default channel that alerts will get sent to\n\nFor example:\n\n```\n-e DISCORD_WEBHOOK_URL=https://discordapp.com/api/webhooks/XXXX -e DISCORD_RECIPIENT=alerts\n```\n\n# Getting alarms in Telegram\n\nNetdata supports sending alerts to Telegram via token and chat ID. You can set that up by setting the following ENV variables:\n\n- TELEGRAM_BOT_TOKEN - This is your bot token\n- TELEGRAM_CHAT_ID - This is the chat ID\n\nFor example:\n\n```\n-e TELEGRAM_BOT_TOKEN=22624413:AAGy12TkSMBYVBTe4lQt3BfUYvUs5h7I1jn -e TELEGRAM_CHAT_ID=137165138\n```\n\nFor more details about Telegram alerts, see [this page - GitHub](https://github.com/firehol/netdata/wiki/health-monitoring#telegramorg-messages)\n\n# Getting alarms in Pushbullet\n\nNetdata supports sending alerts to Pushbullet via API token. You can set that up by setting the following ENV variables:\n\n- PUSHBULLET_ACCESS_TOKEN - This is your API token\n- PUSHBULLET_DEFAULT_EMAIL - This is the default email that alerts will get sent to if there is not a Pushbullet account attached to it\n\nFor example:\n\n```\n-e PUSHBULLET_ACCESS_TOKEN=o.l8VuizWhXgbERf2Q78ghtzb1LDCYvbSD -e PUSHBULLET_DEFAULT_EMAIL=your.email@gmail.com\n```\n\nMore details about Pushbullet alerts are provided [here - GitHub](https://github.com/firehol/netdata/wiki/health-monitoring#pushbulletcom-push-notifications)\n\n# Setting up streaming\n\nOn a client netdata set this destination to be the HOST[:PORT] of the\ncentral netdata, and give an `API_KEY` that is secret and only known internally\nto the netdata clients, and netdata central. See [this page - GitHub](https://github.com/firehol/netdata/wiki/Replication-Overview#options-for-the-sending-node)\n\n- NETDATA_STREAM_DESTINATION - `HOST[:PORT]` to stream to\n- NETDATA_STREAM_API_KEY - `API_KEY` to send to central net data\n\n```\n-e NETDATA_STREAM_DESTINATION=netdata.service:19999 -e NETDATA_STREAM_API_KEY=1h213ch12h3rc1289e\n```\n\nOn the central netdata set 1 or more `NETADATA_API_KEY_ENABLE` env variables that matches the `API_KEY`\nthat you used on the client above, this will enable the netdata client node to communicate with the netdata central\n\n- NETADATA_API_KEY_ENABLE_{API_KEY}=1\n\n```\n-e NETDATA_API_KEY_ENABLE_1h213ch12h3rc1289e=1\n```\n\n# Monitoring docker container metrics\n\nNetdata supports fetching container data from `docker.sock`. You can forward it to the netdata container with:\n\n~~~\n-v /var/run/docker.sock:/var/run/docker.sock:ro\n~~~\n\nThis will allow netdata to resolve container names.\n\n\u003e Note: forwarding docker.sock exposes the administrative docker API. If due to some security issue access has been obtained to the container, it will expose full docker API, allowing to stop, create or delete containers, as well as download new images in the host.\n\u003e\n\u003e TL;DR If you care about security, consider forwarding a secure docker socket with [docker-proxy-acl](https://github.com/titpetric/docker-proxy-acl)\n\n# Monitoring docker notes on some systems (Debian jessie)\n\nOn debian jessie only 'cpu' and 'disk' metrics show up under individual docker containers. To get the memory metric, you will have to add `cgroup_enable=memory swapaccount=1` to `/etc/default/grub`, appending the `GRUB_CMDLINE_LINUX_DEFAULT` variable:\n\n~~~\n$ cat /etc/default/grub  | grep GRUB_CMDLINE_LINUX_DEFAULT\nGRUB_CMDLINE_LINUX_DEFAULT=\"quiet cgroup_enable=memory swapaccount=1\"\n~~~\n\nAfter rebooting your linux instance, the memory accounting subsystem of the kernel will be enabled. Netdata will pick up additional metrics for the containers when it starts.\n\n# Environment variables\n\nIt's possible to pass a NETDATA_PORT environment variable with -e, to start up netdata on a different port.\n\n```\ndocker run -e NETDATA_PORT=80 [...]\n```\n\n# Some explanation is in order\n\nDocker needs to run with the SYS_PTRACE capability. Without it, the mapped host/proc filesystem is not fully readable to the netdata deamon, more specifically the \"apps\" plugin:\n\n```\n16-01-12 07:58:16: ERROR: apps.plugin: Cannot process /host/proc/1/io (errno 13, Permission denied)\n```\n\nSee the following link for more details: [/proc/1/environ is unavailable in a container that is not priviledged](https://github.com/docker/docker/issues/6607)\n\n# Limitations\n\nIn addition to the above requirements and limitations, monitoring the complete network interface list of the host is not possible from within the Docker container. If you're running netdata and want to graph all the interfaces available on the host, you will have to use `--net=host` mode.\n\nSee the following link for more details: [network interfaces missing when mounting proc inside a container](https://github.com/docker/docker/issues/13398)\n\n## Work-around\n\nI provided a script called `fakenet.sh` which provides a copy of the `/proc/net` filesystem. You should start this script before you start the netdata container. You can do it like this:\n\n~~~\nwget https://raw.githubusercontent.com/titpetric/netdata/master/fakenet.sh\nchmod a+x fakenet.sh\nnohup ./fakenet.sh \u003e/dev/null 2\u003e\u00261 \u0026\n~~~\n\nUsing the above command, the fakenet script will start in the background and will keep running there. You can use other tools like `screen` or `tmux` to provide similar capability.\n\nThe script fills out the `/dev/shm/fakenet` location, which you must mount into the container. You *must* mount it into `/fakenet/proc/net` exactly with the option like this:\n\n~~~\n-v /dev/shm/fakenet:/fakenet/proc/net\n~~~\n\nThe script refreshes network information about every 250ms (four times per second). The interval may be increased to give better accuracy of netdata, but CPU usage will also increase. Because of this, the data is not very accurate and some spikes and valleys will occur because of a shifting window between when the reading was taken (fakeproc) and between when the reading was read by netdata. This means the margin for error is whatever data can be collected in ~250ms.\n\nWhile the solution might not fit everybody, it's security-positive because the netdata container can only inspect the fake proc/net location, and can't actually access any of the networks because it runs on a private LAN / custom network which is managed and firewalled by docker. You may even open access via application, like a nginx reverse proxy where you can add authentication etc.\n\nPro/con list:\n\n* + network isolation stays in tact\n* + all network device metrics are available\n* - one more service to provide fakenet\n* - accuracy vs. cpu use is a trade-off\n\n# Additional notes\n\nNetdata provides monitoring via a plugin architecture. This plugin supports many projects that don't provide data over the `/proc` filesystem. When you're running netdata in the container, you will have difficulty providing many of these paths to the netdata container.\n\nWhat you do get (even with the docker version) is:\n\n* Host CPU statististics\n* Host Network I/O, QoS\n* Host Disk I/O\n* Applications monitoring\n* Container surface metrics (cpu/disk per name)\n\nYou will not get detailed application metrics (mysql, ups, etc.) from other containers or from the host if running netdata in a container. It may be possible to get *some* of those metrics, but it might not be easy, and most likely not worth it. For most detailed metrics, netdata needs to share the same environment as the application server it monitors. This means it would need to run either in the same container (not even remotely practical), or in the same virtual machine (no containers).\n\n\u003e Note: if you have some custom hardware like a UPS which is monitored via USB and netdata supports it, you will most likely need to add new software to the netdata docker image to support it. The correct way to do it is to create your own Dockerfile, start with \"FROM titpetric/netdata\" and then add all your installation commands to build your own image which will support your hardware setup. Most likely if it's not a very common setup (i.e. available on most machines), the software will not be added to `titpetric/netdata` - that being said, your use case might be useful for others so feel free to submit issues with your extensions or feature requests in terms of new software. I'll gladly add your project/extension to the README here.\n\n# Changelog\n\n### v1.10.0 -\u003e Latest\n\n* Replaced sSMTP with msmtp, renamed `SSMTP_*` settings as `SMTP_*`, removed `SSMTP_HOSTNAME` setting, renamed `SSMTP_TLS` to `SMTP_STARTTLS` and added `SMTP_TLS`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftitpetric%2Fnetdata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftitpetric%2Fnetdata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftitpetric%2Fnetdata/lists"}