HA-Dockermon – Use Home Assistant to monitor, start or stop Docker Containers

By Phil Hawthorne

Being a developer, I love the flexibility and power Docker brings to Home Automation. Docker makes it easy to run multiple services which can play a big role in your smart home.

It’s no surprise why HASS.IO, the all-in-one solution is also powered by Docker. Using the power of isolated Docker containers, HASS.IO has the ability to keep Home Assistant up-to-date without the need for the command line. It also powers the concept of Home Assistant Add-ons, which are isolated Docker containers, adding their own additional functionality.

Right now, HASS.IO can only be installed on some Linux based systems. My Synology NAS, which I run Docker from is based on Linux but isn’t compatible with HASS.IO. For the time being, I’m still using Home Assistant via the official Home Assistant DockerHub image. This gives me an always-on network server which is more powerful than a Raspberry Pi and allows me to run multiple applications.

Having such power means I end up running a few Docker containers. These include InfluxDB and Grafana, and MySQL for my history and recorder components. You can also take it further with Docker containers for almost anything else: Transmission Download clients, the Plex media server, ad-blocking software PiHole, and of course even more Home Automation tools like HomeBridge for connecting Home Assistant to your iOS devices.

With so many potential Docker containers, they create more moving parts in your smart home. The more moving parts you have, the more things must be up and operational for your smart home to function. If one of those containers goes down, it would be nice for Home Assistant to be able to bring them back up (or at least notify you if it can’t).

 

Introducing HA-Dockermon

Home Assistant has great sensor and switch components that can easily be adapted for wide use-cases. Some of those include the RESTful Sensor and RESTful Switch. These components make it easy for Home Assistant to read data from a REST API, and display or utilise them in Home Assistant either as a switch or sensor.

HA-Dockermon is a NodeJS service which can be run from its own Docker container (or NodeJS if you’re that way inclined). It exposes a RESTful API which Home Assistant can call to see the status of Docker containers on your system. As at the first release, here’s what HA-Dockermon can do:

  • Get the status of a container (running, stopped).
  • Start or stop a container by issuing a POST  request.
  • Restart a container by making a GET  request to a URL for the container.

 

The Latest In Your Inbox

Enter your email address below to receive my latest blog posts and videos about Home Automation in your Inbox

 

Installing with Docker

The easiest way to get going with HA-Dockermon is to run its own Docker container. The trick is to mount the Docker connection socket using a volume mount. This is critical, as it allows the Docker container to access the host Docker instance, and perform actions against the Docker API directly.

The following run command will spin up a Docker container with HA-Dockermon running on port 8126.

The second volume mount is to mount a config directory. You can use this to add a configuration.yaml file to define additional settings like a username and password which must be used to call the service. This mount is optional, and default settings will be used if you don’t set it. See the GitHub repo for the default settings and an example file.

 

Adding to Home Assistant

Because HA-Dockermon is designed to work with RESTful Switches and Sensors, adding these to Home Assistant just requires a few lines of YAML in your configuration file.

Once you’ve added those switches, you can use customise to add some icons, and then use groups to add them to your Home Assistant front-end.

Here’s how that card now looks in Home Assistant

Tapping those switches on or off will send their respective docker start  and docker stop  commands to the containers.

 

Restarting Home Assistant

One problem I have running Home Assistant in a Docker container is that the stop and restart Home Assistant buttons don’t work. For some reason, Home Assistant is unable to stop the container, and the container just hangs with Home Assistant down and unusable. This means each time I make a change to my config that needs a Home Assistant restart, I need to SSH into my Synology NAS to execute docker restart home-assistant .

HA-Dockermon includes a /restart  endpoint which can be added after the container name in the URL. This allows you to simply make a call to a URL to restart a container, like Home Assistant.

Here’s a shell command and script you can add to your Home Assistant which will make a call to HA-Dockermon to restart Home Assistant.

We can then add that to a Home Assistant group, and we’ll see a nice Activate button which will restart the entire Home Assistant Docker container.

 

Adding Alerts

Now that we have those switches inside Home Assistant, we can use them like any other normal switch. For example, we might want to send an alert if the MySQL or MQTT containers crashed and haven’t been up for 5 minutes.

 

Automating When Containers Run/Stop

Another thing we can now do is automate when Docker containers are run or stopped. Here’s an example automation that would shut down a Plex Media Server container when the Harmony Remote turns off the TV after midnight, or at midnight if the TV is already turned off.

 

 

Other Ideas

So far, this has been a great addition to my Home Assistant setup. I now have more visibility into the moving parts of my smart home from within Home Assistant. There’s an extra layer of security knowing that Home Assistant has the ability to inform me that something isn’t right before I or someone else in the house notice.

My use case was pretty basic. To give me the ability to send alerts when something is wrong, and to restart Home Assistant remotely. Of course, you could use this to go a few steps further (and I hope you do). Here are some ideas you could explore with HA-Dockermon.

  • Combine with the Certificate Expiry sensor to have Certbot automatically regenerate an SSL certificate, and then reboot the Home Assistant container when it’s done. This will ensure your Home Assistant always has a valid SSL certificate, and you don’t need to do anything.
  • Voice control Docker containers. Ask Alexa to restart Home Assistant instead of finding the reset button in the UI. Or tell Google Assistant to turn off Transmission because you’re trying to stream Netflix.
  • Detect when your host machine is using too many resources (RAM, CPU etc) and shut down any non-critical Docker containers to improve performance.

 

Eventually, I’d like to add more features to HA-Dockermon such as pulling/updating images, renaming containers etc. You can star or follow the GitHub repo for the latest updates. If you’ve got another idea on how to use HA-Dockermon, I’d love to hear it too!

Recommended Posts
  • ASA

    That is really quite awesome. And its made me realize how many containers I have running that I use once in a blue moon (calibre, Unifi, …) I can now turn them on as I need them from HA 🙂 Thanks!

  • Jokerigno

    Hi!

    It’s still me!

    I’ve tried to setup this metadocker in my home assistant.

    But it does’nt work.

    This is the log I’ve found:

    Unable to connect to Docker socket at /var/run/docker.sock. Is Docker running?
    npm ERR! code ELIFECYCLE
    npm ERR! errno 1
    npm ERR! [email protected] start: node index.js
    npm ERR! Exit status 1
    npm ERR!
    npm ERR! Failed at the [email protected] start script.
    npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

    I tried also to run it as root but nothing change.

    Any hint?

    • Looks like your docker socket might be in a different location. Can you post your docker run command?

      • Jokerigno

        This is what I ran:

        docker run -d
        –name=HomeAssistantDockermon –restart=always
        -v /var/run/docker.sock:/var/run/docker.sock
        -p 8126:8126
        philhawthorne/ha-dockermon

        I checked into my nas. In var/run folder a docker.sock file exist with root as owner.

    • PATER Semper Incertus

      Same error here. I went on and ssh-ed into my Synology, then chmod the sh*t out of /var/run/docker.sock, to 777 … the container ran fine after, even altered its configuration from Synology DSM Docker GUI, then restarted from there … all fine. Hope it helps.

  • Love this. Great implementations, please keep them coming.

    I have a somewhat unrelated question that I hope you can help with. I need to access the usr folder of my Home Assistant container image hosted on a Synology NAS at volume1dockerhass-dev. Where is this usr folder normally located and how do I access it with SSH?

    • So just to confirm, you want to access the folder at /volume1/docker/hass-dev? You should be able to use a program like WinSCP to login with your SSH credentials, and then view the contents

      • Hey Phil, nope. I was told to change settings in this file: /usr/local/lib/python3.6/site-packages/pydaikin/appliance.py
        These changes are needed to get my AC unit fixed, but i have no idea where to access this for a container. I SSH’ed into the DSM usr folder, but python3.6 is not even there… Thanks for your trouble

        • Ah right, yes that directory isn’t mounted by default. You can create a new docker container and mount the dir, however I would advise against this.

          When I need to change those files, here’s what I do.

          From the host machine, execute

          Where home-assistant is the name of your running docker container.

          This will give you access to the containers shell. Now, you can

          Now in your Home Assistant config directory in the NAS you’ll see appliance.py. Make your changes to the file and save it. Then, copy back into the /usr folder by doing the reverse to the command above

          Then exit out of the shell, which will bring you back into the SSH of the NAS, then do a docker restart of the container so your new file changes are loaded.

  • By the way Phil,
    My understanding is that Hass-io cannot currently run as a Synology docker container. I’m interested in using a similar implementation to the Let’s Encrypt!/DuckDNS plug-in for Hass-io. This is needed to use things like Google Assistant that require SSL external access. Have you toyed with this at all?

    • Yeah that’s right. HASS.IO currently isn’t compatible with Synology.

      I have looked into the DuckDNS side of things. I’m surprised Home Assistant doesn’t have a component to do that to be honest.

      I currently don’t use SSL, but might be a good idea for another post once I get it working. There’s a docker image you can use which will generate, or renew a SSL certificate from Let’s Encrypt (called Certbot). I didn’t get very far into automating it though.

      You would essentially create a scheduled task in Synology, to renew the certificates with the certbot container, then restart the Home Assistant container so that it loads the new certificates

      • Ced

        Cheers for that Phil. I’ll give it a try!

  • Ced

    Mmh, I’m having no luck running this one. Here is the code I used (adapted to DSM 6.1):
    ”’docker run -d

    –name=ha-dockermon

    —-mount type=bind,source=/run/docker.sock,target=/run/docker.sock

    -—mount type=bind,source=/volume1/docker/dockermon/config,target=/config

    -p 8126:8126

    philhawthorne/ha-dockermon”’
    The error message I get is
    docker: invalid reference format.
    See ‘docker run –help’.

    Still no luck using -v either…
    Running out of ideas!

    • So strange.

      I’m not sure if it is a copy/paste issue, but I noticed there are two types of dashes in front of the mount there. There’s a long dash and a small dash. Not sure if that might be causing the issues?

      • Ced

        Oh, yeah! I see what you mean… I shall give it another try as soon as I get home. I really see a lot of value to this and hope to make it work!

        • Ced

          Yup, it was indeed a dash issue. Good eyesight! Thanks again Phil…

  • Bernie Blais

    Hi Phil,
    I have been trying to install this component on my Raspberry Pi 3 with no luck, it seems like it never fully starts.
    I would really like to make this work on my side, this is a great addition in my opinion. My preferred method would be through a docker-compose file entry.
    I’m really new to this docker technology, so do you think that I am doing something wrong on my side? Is there a way that I can adapt this somehow to deploy on a Pi? Thanks.

    • Ah yes, I don’t think the base image I’m using runs on Raspberry Pi.

      Lucky though someone else created a fork of mine to create a Raspberry Pi version. See https://hub.docker.com/r/tribunex/ha-dockermon-pi/

      • Bernie Blais

        Thanks Phil, perfect! I just installed it with docker-compose and a file entry similar to yours.
        Thank you for your contribution, much appreciated.

  • Thanks a lot for this, I’ve just got it up and running.

    I noticed if I put the URL of one of my containers in a browser is shows some details
    {“state”:”running”,”status”:”Up 15 hours”,”image”:”linuxserver/transmission:latest”}

    Is there a way for me to show the status (running time) in Home Assistant’s frontend?

    • Hey Jono,

      Glad you’re finding it useful!

      You sure can. This was one of the reasons I wanted to include that, incase someone like you wanted to use that info 🙂

      You can use a RESTfulSensor. https://www.home-assistant.io/components/sensor.rest/

      Be sure to use a GET request (don’t use a POST request), and then use the value template to extract the information you want out. This will add a sensor to Home Assistant you can use in your front end.

      Cheers

  • Kyle Klicker

    This is frickin awesome! I have a fire tv server that kept disconnecting from the stick each time I turned it off. I was manually starting the server each time I turned on the fire stick. Now I put an automation in Home Assistant that detects the Harmony Hub activity and turns it on and off accordingly with the remote. This really opens up my mind to a whole new level of automations. Nice work!

  • Strex

    Hey @philhawthorne:disqus Great work on this!
    Just wondering, is there any way of pulling data from multiple docker instances?
    (and yes, I have 2 synology’s, both running their own docker stacks)

    • Thanks @xstrex:disqus

      Yeah of course. For each Docker instance, just run another HA-Dockermon on that instance.

      So, Synology 1 on IP 192.168.1.2 will run HA-Dockermon, and Synology 2 on IP 192.168.1.3 will also run its own HA-Dockermon.

      Then in your Home Assistant, just make the REST calls to the IP address of the right Synology where the container exists

  • Reggie Suplido

    Thanks for this! Finally I can easily restart node-red correctly on every HA restart.

  • Matthew David Krivanek

    Hi @philhawthorne:disqus Many thanks for creating this. Following your instructions, I’m able to stop and start all of my dockers except for Home Assistant. I see the section you have detailing how to do specifically that but when I click the “Execute” button, I see a push notification–“Turned on Restart Home Assistant”, but it doesn’t actually restart. Any idea what might be wrong?

    • Interesting. Can you post your yaml for the script?

      • Matthew David Krivanek

        In my scripts.yaml, I have:

        restart_hass:
        alias: Restart Home Assistant
        sequence:
        - service: shell_command.restart_hass

        • Matthew David Krivanek

          In configuration.yaml

          shell_command:
          restart_hass: 'curl http://127.0.0.1:8126/container/home-assistant/restart'

          In groups.yaml

          system:
          name: System
          entities:
          - script.restart_hass

          Strangely, if I remove the script from my scripts file and notate it as you do in your article, the System group on my frontend disappears.

          • Hmmmm strange. That all looks ok to me.

            Just to confirm, the container name of your container is set to home-assistant?

            Also, if you go to xxx.xxx.xxx:8126/container/home-assistant/restart in a browser, does it restart your home Assistant instance?

          • Matthew David Krivanek

            Ah! Found the issue. And it’s a silly one at that….my docker for HA is named homeassistant (without the dash). Updated to reflect the correct path and it works!!! Thanks for the help and for creating HA-Dockermon.

          • Michael McGuinness

            Hi Phil,

            Having a similar issue to Matthew (My on off switch works fine and the API call works as well, http://mynasaddress:8126/container/home-assistant/restart). However I have reviewed all the code Matthew posted and mine looks correct. I did not get from your guide to add the stuff into the scripts.yaml (it says configuration.yaml twice)? But done that now.

            I still can’t get it to the system group to show (with the restart button). I can see that group.system is in my list of Unused entities but has a status of unknown. Could I get some guidance please?

            Here is my config.

            configuration.yaml

            #Docker Manager
            #home-assistant docker
            switch:
            - platform: rest
            resource: http://127.0.0.1:8126/container/home-assistant
            name: home-assistant
            body_on: '{"state": "start"}'
            body_off: '{"state": "stop"}'
            is_on_template: '{{ value_json is not none and value_json.state == "running" }}'

            shell_command:
            restart_hass: 'curl http://127.0.0.1:8126/container/home-assistant/restart'

            scripts.yaml

            script:
            restart_hass:
            alias: Restart Home Assistant
            sequence:
            - service: shell_command.restart_hass

            groups.yaml

            system:
            name: System
            entities:
            - script.restart_hass

            Thanks heaps

          • Interesting, nothing looks to be wrong there.

            If you go to /container/home-assistant/restart in your browser, does it work?

          • Michael McGuinness

            Sure does, I use that every time I make changes to my config. Just using the NAS mount on my mac to access the files.

          • Ok interesting. Could be a network issue. Can you try use the IP address of your host, instead of 127.0.0.1?

          • Michael McGuinness

            @philhawthorne:disqus Thanks for your speedy reply. I fixed it. I just went back and reviewed what code Matthew had, in my Scripts file I had “script:” on the top line, once I removed that it works as expected. Awesome. What got me looking at this was in the notification area it said there was an error in my scripts file. So I knew to look there, will keep that in mind next time I an issue 🙂

  • Nasked

    Hi:
    After configure your dockermon container, i writted your containeralert.yaml with code:

    alias: Container_offline
    initial_state: 'on'
    trigger:
    - platform: state
    entity_id: switch.mqtt, switch.portainer
    to: 'off'
    for:
    minutes: 5
    condition:
    condition: and
    conditions:
    # Only send this once per hour
    - condition: template
    value_template: >
    {% if states.automation.container_offline.last_triggered is not none %}
    {% if as_timestamp(now()) | int - as_timestamp(states.automation.container_offline.attributes.last_triggered) | int > 3600 %} true {% else %} false
    {% endif %}
    {% else %}
    false
    {% endif %}
    action:
    - service: notify.naskedbot
    data_template:
    message: 'El contenedor {{ trigger.to_state.name }}no funciona.'
    title: Alerta Contenedor
    - service: persistent_notification.create
    data_template:
    notification_id: offline_container
    title: Contenedor desconectado
    message: 'El contenedor {{ trigger.to_state.name }}no funciona.'

    Triggering automation HA show me this error:

    Error rendering data template: UndefinedError: ‘trigger’ is undefined

    thanks in advance…

    • Hey Nasked,

      When manually triggering an automation from the Home Assistant UI, the “trigger” variable won’t be set. The only real way to test that automation would be to shut down that container and wait the 5 minutes

      • Nasked

        I stopped container by ssh cli and wait 5 minutes, but automation doesn’t works. Also log send: Error rendering data template: UndefinedError: ‘trigger’ is undefined
        9:40 helpers/service.py (ERROR)

        • Hmm interesting. I am wondering if there’s an issue with my code here.

          You might have to use

          in the template instead.

          Let me know how you go, and if that works I’ll update the examples.

          • Nasked

            Nothing, i used it in template but automotion not run. Actually my code is:

            – alias: Container_offline
            initial_state: ‘on’
            trigger:
            – platform: state
            entity_id: switch.mqtt
            to: ‘off’
            for:
            minutes: 5
            condition:
            condition: and
            conditions:
            # Only send this once per hour
            – condition: template
            value_template: >
            {% if states.automation.container_offline.last_triggered is not none %}
            {% if as_timestamp(now()) | int – as_timestamp(states.automation.container_offline.attributes.last_triggered) | int > 3600 %} true {% else %} false
            {% endif %}
            {% else %}
            false
            {% endif %}
            action:
            – service: notify.naskedbot
            data_template:
            message: ‘El contenedor {{ trigger.to_state.attributes.friendly_name }}no funciona.’
            title: Alerta Contenedor
            – service: persistent_notification.create
            data_template:
            notification_id: offline_container
            title: Contenedor desconectado
            message: ‘El contenedor {{ trigger.to_state.attributes.friendly_name }}no funciona.’

  • Michael McGuinness

    Hi,

    I am getting the following error once I try to start the docker image.

    2019-01-07 12:15:05 stderr npm ERR! /root/.npm/_logs/2019-01-07T12_15_04_637Z-debug.log
    2019-01-07 12:15:05 stderr npm ERR! A complete log of this run can be found in:
    2019-01-07 12:15:05 stderr
    2019-01-07 12:15:04 stderr npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
    2019-01-07 12:15:04 stderr npm ERR! Failed at the [email protected] start script.
    2019-01-07 12:15:04 stderr npm ERR!
    2019-01-07 12:15:04 stderr npm ERR! Exit status 1
    2019-01-07 12:15:04 stderr npm ERR! [email protected] start:     node index.js
    2019-01-07 12:15:04 stderr npm ERR! errno 1
    2019-01-07 12:15:04 stderr npm ERR! code ELIFECYCLE
    2019-01-07 12:15:04 stderr at startup (bootstrap_node.js:193:16)
    2019-01-07 12:15:04 stderr at Function.Module.runMain (module.js:701:10)
    2019-01-07 12:15:04 stderr at Function.Module._load (module.js:505:3)
    2019-01-07 12:15:04 stderr at tryModuleLoad (module.js:513:12)
    2019-01-07 12:15:04 stderr at Module.load (module.js:573:32)
    2019-01-07 12:15:04 stderr at Object.Module._extensions..js (module.js:671:10)
    2019-01-07 12:15:04 stderr at Module._compile (module.js:660:30)
    2019-01-07 12:15:04 stderr at Object. (/usr/src/app/index.js:18:8)
    2019-01-07 12:15:04 stderr at Object.file (/usr/src/app/node_modules/merge-config/lib/configuration.js:200:20)
    2019-01-07 12:15:04 stderr at TherrorNamespace.errorConstructor (/usr/src/app/node_modules/therror/lib/therror.js:171:17)
    2019-01-07 12:15:04 stderr ^
    2019-01-07 12:15:04 stderr customize: !include customize.yaml
    2019-01-07 12:15:04 stderr FILE_INVALID: Invalid configuration file: "/config". unknown tag ! at line 14, column 37:
    2019-01-07 12:15:04 stderr ^
    2019-01-07 12:15:04 stderr throw errors.FILE_INVALID(filePath, e.message);
    2019-01-07 12:15:04 stderr /usr/src/app/node_modules/merge-config/lib/configuration.js:200
    2019-01-07 12:15:04 stderr
    2019-01-07 12:15:04 stdout Loading settings from /config

    Any ideas, I also used your other setup guide to setup home assistant of my Nas using Docker. I think from some reason I am missing the part where I mount the folder for it to read from the hass main docker?

    https://uploads.disquscdn.com/images/6044393422a13e85034fce33fca2a00619d915d50d5132cc36dcebb28033baf5.png https://uploads.disquscdn.com/images/65542b0b41a3ad298a8be07277f1316cdf7d1a48464009ffe8baadc8fbee667b.png

    • It looks like you’ve mounted the Home Assistant configs into HA-Dockermon. HA-Dockermon has its own configuration.yaml file, which you should mount in its own folder.

      I would suggest creating a docker/hadockermon/config folder on your NAS.

      • Michael McGuinness

        Thanks heaps, all fixed.

Start typing and press Enter to search