{"id":13583737,"url":"https://github.com/philhawthorne/ha-dockermon","last_synced_at":"2025-05-16T14:04:42.537Z","repository":{"id":28258048,"uuid":"117817868","full_name":"philhawthorne/ha-dockermon","owner":"philhawthorne","description":"A NodeJS RESTful API which can be used with Home Assistant to report the state of Docker Containers","archived":false,"fork":false,"pushed_at":"2025-04-05T05:16:48.000Z","size":677,"stargazers_count":278,"open_issues_count":57,"forks_count":32,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-19T15:56:34.290Z","etag":null,"topics":["docker","docker-container","docker-socket","hacktoberfest","home-assistant","home-automation","nodejs","restful-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philhawthorne.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-17T09:57:33.000Z","updated_at":"2025-04-13T00:20:24.000Z","dependencies_parsed_at":"2024-11-15T21:29:38.817Z","dependency_job_id":"06292a96-6e17-4968-a7a5-f7b33de014bc","html_url":"https://github.com/philhawthorne/ha-dockermon","commit_stats":{"total_commits":82,"total_committers":12,"mean_commits":6.833333333333333,"dds":0.5365853658536586,"last_synced_commit":"044d7470f40a3ca36fb3f2afe64dda095146d476"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philhawthorne%2Fha-dockermon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philhawthorne%2Fha-dockermon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philhawthorne%2Fha-dockermon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philhawthorne%2Fha-dockermon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philhawthorne","download_url":"https://codeload.github.com/philhawthorne/ha-dockermon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"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","docker-container","docker-socket","hacktoberfest","home-assistant","home-automation","nodejs","restful-api"],"created_at":"2024-08-01T15:03:44.856Z","updated_at":"2025-05-16T14:04:42.507Z","avatar_url":"https://github.com/philhawthorne.png","language":"JavaScript","funding_links":["https://www.buymeacoffee.com/philhawthorne"],"categories":["Uncategorized","JavaScript"],"sub_categories":["Twitter"],"readme":"HA Dockermon\n============\n\n[![Docker Pulls](https://img.shields.io/docker/pulls/philhawthorne/ha-dockermon.svg)](https://dockerhub.com/philhawthorne/ha-dockermon) [![Build Status](https://travis-ci.org/philhawthorne/ha-dockermon.svg?branch=master)](https://travis-ci.org/philhawthorne/ha-dockermon) [![license](https://img.shields.io/github/license/philhawthorne/ha-dockermon.svg)](https://dockerhub.com/philhawthorne/ha-dockermon)\n\n[![Buy me a coffee][buymeacoffee-icon]][buymeacoffee]\n\n\nThis is a simple Node service which checks the status of a Docker Container and returns a RESTful response. It can also be used to issue `start` `stop` `pause` `unpause` and `restart` commands. The primary purpose of this service is to interface with [Home Assistant](https://home-assistant.io) on a [Synology NAS](http://amzn.to/2FAC28A).\n\n## Supported Features\nAs of this release, you can:\n\n* Get the status of a container (running, stopped, paused).\n* Start, stop, pause, or unpause a container by issuing a `POST` request.\n* Start, stop, pause, or unpause a container by issuing a `GET` requst.\n* Restart a container by making a `GET` request to a URL for the container (details below).\n* Execute commands inside a container using the `/exec` endpoint of a container.\n\n## Getting Started\n\n### Configuration Options\nYou can change some configuration options for this service by editing config/configuration.yaml.\n\n| Option                 | Description                                                                                                      | Default Value        |\n|------------------------|------------------------------------------------------------------------------------------------------------------|----------------------|\n| debug                  | If set to true, will output some helpful debug messages to the console.                                          | false                |\n| http.port              | The HTTP port the service listens on. Must be a valid HTTP port or windows socket.                                                                          | 8126                 |\n| http.username          | If set all calls to this service must use HTTP basic authentication with this username. **If set, must not be an empty value.**                         | None                 |\n| http.password          | If set all calls to this service must use HTTP basic authentication with this password. **If set, must not be an empty value.**                         | None                 |\n| docker_connection.type | How the service connects to docker. Valid options are socket or http                                             | socket               |\n| docker_connection.path | The path to the Docker socket. Useful when running this service on the host directly (not in a Docker container) | /var/run/docker.sock |\n| docker_connection.host | The host IP/Domain of the host Docker to connect to. Only used when `docker_connection.type` is set to `http`. **If set, must not be an empty value.**         | None                 |\n| docker_connection.port | The port of the host Docker to connect to. Only used when `docker_connection.type` is set to `http`.  **If set, must not be an empty value.**                  | None                 |\n\n### Connecting to Docker\n\n#### Docker Socket (Recommended)\nThe most secure and reliable way to connect to the Docker service is by connecting to the Docker socket. Generally this is `/var/run/docker.sock`. It may be in a different location on your host, so you may need to mount the correct location with `-v` when using `docker run`. If running directly on the host with NodeJS, be sure to set the correct file path in config/configuration.yaml.\n\n#### HTTP\nYou can expose the Docker Remote API over a HTTP port. This could allow other systems or parties to control the Docker containers on your host and is not recommended.\n\nEnabling an external HTTP port for Docker is beyond the scope of this readme.\n\n\n### Running\n\n#### Docker (Recommended)\nThe easiest way to get started is to run this service inside its own Docker container. You don't need to give any elevated permissions for this service to work however, you must mount the Docker socket to the container from the host (or specify a HTTP connection in the configuration.yaml file).\n\n```bash\ndocker run -d \\\n--name=ha-dockermon --restart=always \\\n-v /var/run/docker.sock:/var/run/docker.sock \\\n-v /path/to/config:/config \\\n-p 8126:8126 \\\nphilhawthorne/ha-dockermon\n```\n\n#### Docker Compose\nIf you prefer to use Docker Compose, here is a sample entry you can add to your Docker compose file.\n```yaml\n  docker_mon:\n    image: philhawthorne/ha-dockermon\n    container_name: ha_dockermon\n    restart: always\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /path/to/config:/config\n    ports:\n      - 8126:8126\n```\n\n#### NodeJS\nYou can run this service directly from a host that has NPM and NodeJS installed. Just checkout this repository and then run:\n\n    npm start\n\n## Raspberry Pi and other versions\nA Raspberry Pi image is available if you wish to use this on a pi. Simply use the `arm` tag, for example:\n\n```bash\ndocker run -d \\\n--name=ha-dockermon --restart=always \\\n-v /var/run/docker.sock:/var/run/docker.sock \\\n-v /path/to/config:/config \\\n-p 8126:8126 \\\nphilhawthorne/ha-dockermon:arm\n```\n\nYou may also use an older version. Check [Docker Hub](https://hub.docker.com/r/philhawthorne/ha-dockermon/tags/) for the list of tags you may use.\n\nIn order to make arm CPU's report memory usage add the following to your kernel command line located at `/boot/cmdline.txt`.\n```\ncgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1\n```\n## Using this service\n\n### HTTP Endpoints\nThis service exposes the following HTTP endpoints\n\n#### GET /container/{container name}\n\nUse this endpoint to get the status of a container, for example, you may make a call to `http://127.0.0.1:8126/container/home-assistant`. The response will be a JSON object in the format below.\n\n```json\n{\n    \"state\":\"running\",\n    \"status\":\"Up About a minute\",\n    \"image\":\"homeassistant/home-assistant:latest\"\n}\n```\n\n#### POST /container/{container name}\n\nUse the same endpoint with `POST` to start or stop a container. When making a call to this endpoint you must send the correct `Content-Type` headers and JSON as the body. An example request with cURL is below.\n\nValid options for `state` are `start`, `stop`, `pause`, and `unpause` to start, stop, pause, or unpause a container respectively.\n\n```bash\ncurl --request POST \\\n--url http://127.0.0.1:8126/container/grafana \\\n--header 'content-type: application/json' \\\n--data '{\"state\": \"start\"}'\n```\n\nThe response will be the same format as the `GET` call above.\n\n#### GET /container/{container name}/restart\n\nCalls to this URL will issue a `docker restart \u003ccontainer name\u003e` on the host machine. There is currently no response from the API to this request.\n\nUseful in a Home Assistant script to restart containers (including Home Assistant itself).\n\n#### POST /container/{container name}/exec\n\nAllows you to execute commands inside a running container. When making a call to this endpoint you must send the correct `Content-Type` headers and JSON as the body. An example request with cURL is below.\n\nYou must also send a `command` variable which contains the command you would like to run in the container.\n\n```bash\ncurl --request POST \\\n--url http://127.0.0.1:8126/container/grafana/exec \\\n--header 'content-type: application/json' \\\n--data '{\"command\": \"ls -a\"}'\n```\n\n### GET /container/{container name}/start\n\nAllows you to send a simple HTTP request to start a Docker container.\n\nThe response will be a json object with a `result` key containing the output from the command executed.\n\n*Warning:* There is no confirmation for the command to be executed. Going to the URL in your browser will start the container.\n\n### GET /container/{container name}/stats\n\nAllows you to read various statistics of a running Docker container, including CPU usage and memory usage.\n\nThe response will be a json object with various keys including `precpu_stats` `cpu_stats` and `memory_stats`. The information returned may vary on the version of Docker your host machine is running.\n\n*Heads Up:* There's a known issue where some host systems (like Synology NAS) may not return a response when calling this endpoint.\n\nThanks to [@thelittlefireman](https://github.com/thelittlefireman) for contributing this endpoint.\n\n### GET /container/{container name}/stop\n\nAllows you to send a simple HTTP request to stop a Docker container.\n\nThe response will be a json object with a `result` key containing the output from the command executed.\n\n*Warning:* There is no confirmation for the command to be executed. Going to the URL in your browser will stop the container.\n\n### GET /container/{container name}/pause\n\nAllows you to send a simple HTTP request to pause a Docker container.\n\nThe response will be a json object with a `result` key containing the output from the command executed.\n\n*Warning:* There is no confirmation for the command to be executed. Going to the URL in your browser will pause the container.\n\n### GET /container/{container name}/unpause\n\nAllows you to send a simple HTTP request to unpause a Docker container.\n\nThe response will be a json object with a `result` key containing the output from the command executed.\n\n*Warning:* There is no confirmation for the command to be executed. Going to the URL in your browser will unpause the container.\n\n### GET /containers\n\nOutputs a list of all stopped, started, and paused containers on the host.\n\nThis is the same as performing a `docker ps -a` command on the host machine.\n\nThe response will be a json object, with each container in its own key. An example response is below.\n\n```json\n[{\n\t\"Id\": \"2096eaf1a58f1730234d2e30c982021c196192eae9f41c6abf8fa26aad348477\",\n\t\"Names\": [\"/hadockermon\"],\n\t\"Image\": \"hadockermon\",\n\t\"ImageID\": \"sha256:e7352295ec274a441f691a8c83f8823137654f5d4df5fb187d9f1cee1f4711d6\",\n\t\"Command\": \"/bin/sh -c 'npm start'\",\n\t\"Created\": 1523522864,\n\t\"Ports\": [{\n\t\t\"IP\": \"0.0.0.0\",\n\t\t\"PrivatePort\": 8126,\n\t\t\"PublicPort\": 8126,\n\t\t\"Type\": \"tcp\"\n\t}],\n\t\"Labels\": {},\n\t\"State\": \"running\",\n\t\"Status\": \"Up 19 seconds\",\n\t\"HostConfig\": {\n\t\t\"NetworkMode\": \"default\"\n\t},\n\t\"NetworkSettings\": {\n\t\t\"Networks\": {\n\t\t\t\"bridge\": {\n\t\t\t\t\"IPAMConfig\": null,\n\t\t\t\t\"Links\": null,\n\t\t\t\t\"Aliases\": null,\n\t\t\t\t\"NetworkID\": \"ed342d9b95ab77f57172ca3fdd2dc87682ee7e0c3f94db7bb3a83ba81a5f2135\",\n\t\t\t\t\"EndpointID\": \"bfdec2f98a2521093e1210c1cc5135e3a788be5b80b8409d8652915a5ee38224\",\n\t\t\t\t\"Gateway\": \"172.17.0.1\",\n\t\t\t\t\"IPAddress\": \"172.17.0.2\",\n\t\t\t\t\"IPPrefixLen\": 16,\n\t\t\t\t\"IPv6Gateway\": \"\",\n\t\t\t\t\"GlobalIPv6Address\": \"\",\n\t\t\t\t\"GlobalIPv6PrefixLen\": 0,\n\t\t\t\t\"MacAddress\": \"02:42:ac:11:00:02\"\n\t\t\t}\n\t\t}\n\t},\n\t\"Mounts\": [{\n\t\t\"Source\": \"/var/run/docker.sock\",\n\t\t\"Destination\": \"/var/run/docker.sock\",\n\t\t\"Mode\": \"\",\n\t\t\"RW\": true,\n\t\t\"Propagation\": \"rprivate\"\n\t}]\n}]\n```\n\n### Home Assistant RESTful Switch\n\nYou can use this service as a [RESTful switch](https://home-assistant.io/components/switch.rest/) inside Home Assistant.\n\n```yaml\nswitch:\n  - platform: rest\n    resource: http://127.0.0.1:8126/container/grafana\n    name: Grafana\n    body_on: '{\"state\": \"start\"}'\n    body_off: '{\"state\": \"stop\"}'\n    headers:\n      Content-Type: application/json\n    is_on_template: '{{ value_json is not none and value_json.state == \"running\" }}'\n    \nswitch:\n  - platform: rest\n    resource: http://127.0.0.1:8126/container/mosquitto\n    name: Mosquitto\n    body_on: '{\"state\": \"unpause\"}'\n    body_off: '{\"state\": \"pause\"}'\n    headers:\n      Content-Type: application/json\n    is_on_template: '{{ value_json is not none and value_json.state == \"running\" }}'\n```\n### Home Assistant Custom Component\n\nThanks to [Joakim Sørensen (@ludeeus)](https://github.com/ludeeus) you can use a custom Home Assistant Component, which can automatically add switches to your Home Assistant instance from Dockermon.\n\nYou can get the custom component [here](https://gitlab.com/custom_components/hadockermon).\n\n# Further Reading\nFor more in-depth Home Assistant examples and some ideas for use, please check out [this article on my blog](https://philhawthorne.com/ha-dockermon-use-home-assistant-to-monitor-start-or-stop-docker-containers).\n\n[buymeacoffee-icon]: https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-2.svg\n[buymeacoffee]: https://www.buymeacoffee.com/philhawthorne\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilhawthorne%2Fha-dockermon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilhawthorne%2Fha-dockermon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilhawthorne%2Fha-dockermon/lists"}