Home Assistant Containerized

Home Asisstant containerized with docker-compose

Goal of this project

This project aims for easy setup and maintainability.

As Home Asisstant (HA) offers a lot of possibilities out of the box this project focuses on adding functionality that expands connectivity or adds value by useful functionality. MQTT and ZigBee allows to connect to a lot of devices.

Setup

Secrets

Personal data and secrets for docker-compose are stored in a .env file. Secrets for mosquitto will be generated by the user and then stored in the mosquitto/ folder.

User and Group (for mosquitto)

Mosquitto will use UID 1883 as default. You can add a corresponding user to your system and add your user to the group.

 $ sudo groupadd --gid 1883 mosquitto
 $ sudo useradd --no-create-home -g mosquitto --uid 1883 mosquitto
 $ sudo usermod -aG mosquitto USERNAME

mosquitto (MQTT broker)

• The mosquitto setup is inspired by vvatelot mosquitto-docker-compose
• mosquitto is used as MQTT broker.
• Config, logs and persistent data is stored in a separate mosquitto/ folder.
• This setup uses usename and password for authentication.

Optionally you could add more security by adding TLS: Mosquitto TLS

• To allow the mosquitto container access to its files I recommend to give the used user and group access:

  $ sudo chown -R 1883:1883 mosquitto/

• To set up the login run:

  $ docker-compose up -d mosquitto

• And substitute "<USERNAME>" "<PASSWORD>" to generate an according entry in mosquitto/config/password.txt

  $ docker-compose exec mosquitto mosquitto_passwd \
    -b /mosquitto/config/password.txt <USERNAME> <PASSWORD>
  $ docker-compose restart

• The same command can be used to update a password.

NOTE:
"mosquitto_passwd -b" option should be used with care because the password will be visible on the command line and in command history. Find more details here: mosquitto_passwd manpage

• To test the command install a mosquitto client:

  Arch
  $ sudo pacman -S mosquitto  
  UBUNTU
  $ sudo apt-get install mosquitto-clients

• And run the following command in one terminal (nothing will happen as it only starts listening):

  $ mosquitto_sub -h localhost -t "hello/world"

• Then run in another terminal:

  $ mosquitto_pub -h localhost -u <USERNAME> -P <PASSWORD> -t hello/world -m "Hi"

This example uses mosquitto but any other MQTT client should work.

• mosquitto.conf

password_file /mosquitto/config/password.txt
allow_anonymous false
user mosquitto
listener 1883
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

zigbee2mqtt

https://www.zigbee2mqtt.io

Allows you to use your Zigbee devices without the vendors bridge/gateway. It act as a "driver" for a Zigbee Adapter. List of supported devices

Prerequisites

• At first you need to have a supported Zigbee Adapter:
  • https://www.zigbee2mqtt.io/guide/supported-hardware.html
  • I started with a CC2531 and upgraded to SONOFF Zigbee 3.0 USB Dongle Plus
• Then you find the location of the device:
  • https://www.zigbee2mqtt.io/guide/installation/01_linux.html#determine-location-of-the-adapter-and-checking-user-permissions

Setup

• The setting for zigbee2mqtt can be set in the docker-compose.yaml as env vars
• A basic config is in the zigbee2mqtt folder
• The documentation provides a lot of further possibilities docu
• To improve security it is highly recommended to use a custom network key. Because the default key is well known. set custom network key:

Troubleshooting

A change of zigbee2mqtt config file or docker-compose env variables does not get applied:

• After the config of zigbee2mqtt changed do docker compose down (not just restart)

I changed the network_key but get an error of an already existing pan_id! This is annoying but you have 2 options:

• 1. Try to reduce! the range of your zigbee device (remove antenna) and try again
• 2. Change the pan_id in the config

Home Assistant Configuration

To use the full potential of HA you can start on the following link and study the given examples: https://www.home-assistant.io/docs/configuration/

If you have set up your first devices you may want to do something smart: https://community.home-assistant.io/tags/c/blueprints-exchange/53/zigbee2mqtt