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

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.


docker run -d \
--name=ha-dockermon --restart=always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/config:/config \
-p 8126:8126 \
philhawthorne/ha-dockermon

docker run -d \

--name=ha-dockermon --restart=always \

-v /var/run/docker.sock:/var/run/docker.sock \

-v /path/to/config:/config \

-p 8126:8126 \

philhawthorne/ha-dockermon

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.


switch:
  - platform: rest
    resource: http://127.0.0.1:8126/container/grafana
    name: Grafana
    body_on: '{"state": "start"}'
    body_off: '{"state": "stop"}'
    is_on_template: '{{ value_json is not none and value_json.state == "running" }}'

switch:

- platform: rest

resource: http://127.0.0.1:8126/container/grafana

body_on: '{"state": "start"}'

body_off: '{"state": "stop"}'

is_on_template: '{{ value_json is not none and value_json.state == "running" }}'

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.


switch.grafana:
  icon: mdi:chart-line-variant

switch.grafana:

icon: mdi:chart-line-variant


docker_containers:
  name: Docker Containers
  control: hidden
  entities:
    - switch.mqtt
    - switch.grafana
    - switch.mysql

docker_containers:

control: hidden

entities:

- switch.mqtt

- switch.grafana

- switch.mysql

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.


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

shell_command:

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


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

script:

restart_hass:

alias: Restart Home Assistant

sequence:

- service: shell_command.restart_hass

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.


system:
  name: System
  entities:
    - script.restart_hass

system:

entities:

- script.restart_hass

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.


- alias: Alert when a critical container goes offline
  initial_state: 'on'
  trigger:
    - platform: state
      entity_id: switch.mqtt, switch.mysql
      to: 'off'
      for:
        minutes: 5
  condition:
    condition: and
    conditions:
      # Only send this once per hour
      - condition: template
        value_template: >
          {% if states.automation.alert_when_a_critical_container_goes_offline.last_triggered is not none %}
            {% if as_timestamp(now()) | int   -  as_timestamp(states.automation.alert_when_a_critical_container_goes_offline.attributes.last_triggered) | int > 3600 %} true {% else %} false
            {% endif %}
          {% else %}
          false
          {% endif %}
  action:
    - service: notify.phil
      data_template:
        message: 'Docker container for {{ trigger.to_state.name }} is not running. Please check the status of this container as some features may stop functioning.'
        title: Container Alert
    - service: persistent_notification.create
      data_template:
        notification_id: offline_container
        title: Container Offline
        message: >
          Docker container for {{ trigger.to_state.name }} is not running. Please check the status of this container as some features may stop functioning.

- alias: Alert when a critical container goes offline

initial_state: 'on'

trigger:

- platform: state

entity_id: switch.mqtt, switch.mysql

to: 'off'

for:

minutes: 5

condition:

condition: and

conditions:

# Only send this once per hour

- condition: template

value_template: >

{% if states.automation.alert_when_a_critical_container_goes_offline.last_triggered is not none %}

{% if as_timestamp(now()) | int - as_timestamp(states.automation.alert_when_a_critical_container_goes_offline.attributes.last_triggered) | int > 3600 %} true {% else %} false

{% endif %}

{% else %}

false

{% endif %}

action:

- service: notify.phil

data_template:

message: 'Docker container for {{ trigger.to_state.name }} is not running. Please check the status of this container as some features may stop functioning.'

title: Container Alert

- service: persistent_notification.create

data_template:

notification_id: offline_container

title: Container Offline

message: >

Docker container for {{ trigger.to_state.name }} is not running. Please check the status of this container as some features may stop functioning.

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.


- alias: Stop Plex Media Server at night
  trigger:
    - platform: time
      at: '00:00:00'
    - platform: state
      entity_id: remote.living_room
      to: 'off'
  condition:
    condition: and
    conditions:
      - condition: state
        entity_id: switch.plex_container
        state: 'on'
      - condition: state
        entity_id: remote.living_room
        state: 'off'
      - condition: time
        before: '06:00:00'
  action:
    - service: homeassistant.turn_off
      entity_id: switch.plex_container

- alias: Stop Plex Media Server at night

trigger:

- platform: time

at: '00:00:00'

- platform: state

entity_id: remote.living_room

to: 'off'

condition:

condition: and

conditions:

- condition: state

entity_id: switch.plex_container

state: 'on'

- condition: state

entity_id: remote.living_room

state: 'off'

- condition: time

before: '06:00:00'

action:

- service: homeassistant.turn_off

entity_id: switch.plex_container

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!

Buy me a hot chocolate