Docker Discovery

Features

• Run in Docker
• Run as standalone Clojure app
• Supports local or remote Docker API
• Fully configurable
  • Configure multiple Docker hosts
  • Disable / enable many aspect of the discovery
  • Supports config-file or environment variables configuration
• REST API
• Receive Docker events
  • Through WebSockets
  • Through MQTT
• Start / stop Docker containers
• HomeAssistant MQTT discovery compatible
• Docker container attributes available as entity attributes in HomeAssistant.

Installation

TODO

Docker

docker run......

Docker compose

version: "3.8"

Configuration

You can either configure the app using an edn file, or by specifying environment variables.

Multi-value properties

EDN: Keyword-values inside a set, ex.: #{:mqtt :rest}

Environment properties: Comma-separated string-value, ex.: "mqtt,rest"

Properties

See the server README

Security

To enable basic authentication on the REST and WebSocket endpoints, set the http.username and http.password properties. If you don't need the REST API, I recommend disabling it by omitting it from the docker.exposure property.

SSL

Docker Discovery doesn't provide a built-in solution for HTTPS or WSS. I recommend placing something like Nginx in front to provide that functionality. I can recommend Nginx Proxy Manager 👍 With that you can also handle authentication (basic auth) in the proxy manager instead, it gives more flexibility.

MQTT

Set the MQTT username and password properties if your broker requires authentication.

HomeAssistant

When enabled, Docker Discovery will publish HomeAssistant supported messages to MQTT.

Each Docker host will become a device and the containers will become switches for that respective device.

The switches will have some container attributes available on the entity.

WebSockets

You can find the websocket api here.

Future plans

Functional enhancements

• Make more of the features configurable.
• More Docker information available through REST API, without duplicating the original Docker API.
• Handle more Docker events.
• Support other MQTT platforms than HomeAssistant (?)
• Create a custom HomeAssistant integration making use of the WebSockets event. This will be a separate repo of course.
• Create a custom HomeAssistant Lovelace card displaying more of the Docker container attributes etc. Also a separate repo.

Technical improvements

• Use component to manage application lifecycle.
• Use reitit as router.

Keywords

Docker, Home Assistant, Clojure, Websockets, MQTT

License

MIT License

Copyright (c) 2021 Eirik Stenersen Sand

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.