Home Assistant install with docker-compose

Today we are going to see how to install Home Assistant and some complements on docker using a docker-compose file. Consequently, this stack will provide the following services:

• hass, the core of Home Assistant.
• mariadb, to replace the default database engine SQLite.
• mosquitto, a well known open source mqtt broker.
• nodered, a browser-based flow editor to write your automations.
• hass-configurator, a filesystem-browser and text-editor for your configuration files.

In addition, we will be able to install portainer, a web application to manage your containers easily.

This procedure has been tested in arm (Raspberry Pi) and x86_64 architectures. For instructions on how to install docker and docker-compose on your Raspberry Pi you can check this article.

.env file

A few environment variables will be declared in a file named .env, in the same directory where the docker-compose file is. As a result, these variables will be populated later into our docker-compose file at the moment the containers are created.

Security advise

The purpose of this stack is to have a working Home Assistant installation with some accessories. This means that it is not secure by default so you should NEVER expose it to the internet as is. I will explain some steps to secure it in a next article, for example how to password protect Node-RED and hass-configurator and how to hide Home Assistant behind a reverse proxy like nginx using ssl certificates.

Preparation

Create a directory where we will put all needed config and our docker-compose file itself. As an example, I will be using a directory named ‘hass’. We will then precreate a directory structure to maintain configuration and data of the services. To clarify, structure will be as shown below and should be created as a normal non-root user.

pi@raspberrypi:~/hass $ tree -a
.
├── configurator-config
│   └── settings.conf
├── docker-compose.yaml
├── .env
├── hass-config
│   └── configuration.yaml
├── mariadb
├── mosquitto
│   ├── config
│   │   └── mosquitto.conf
│   ├── data
│   └── log
└── nodered

The content of the required files is as follows:

• configurator-config/settings.conf

{
    "BASEPATH": "../hass-config"
}

• .env: This file will hold the root password for mariadb and the password for the ha_db database, so fill them with your preferences. PUID and PGID will be the uid and gid of the user who created the directory structure, you can check these ids typing ‘id’ as that user.

MYSQL_ROOT_PASSWORD=mariadbrootpassword
HA_MYSQL_PASSWORD=ha_dbdatabasepassword
PUID=1000
PGID=1000

• hass-config/configuration.yaml: This will be the basic configuration file for Home Assistant, replace <hostip> with the internal ip of the host where the docker engine is installed and <ha_dbdatabasepassword> with the password you chose for the ha_db database

default_config:

# For homeassistant v2021.7.0 and above add this http block
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - XXX.XXX.XXX.XXX # Add the IP address of the proxy server

panel_iframe:
  configurator:
    title: Configurator
    icon: mdi:wrench
    url: http://<hostip>:3218/
    require_admin: true
  nodered:
    title: Node-Red
    icon: mdi:shuffle-variant
    url: http://<hostip>:1880/
    require_admin: true

mqtt:
  broker: <hostip>
  
recorder:
  db_url: mysql://homeassistant:<ha_dbdatabasepassword>@<hostip>/ha_db?charset=utf8
  purge_keep_days: 30

• mosquitto/config/mosquitto.conf: minimal config for mosquitto

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

listener 1883
allow_anonymous true

docker-compose file

Finally here is our docker-compose.yaml file. As this is a yaml file, be aware about keeping the correct indentation. This file works for Raspberry Pi. For x86_64 architecture you should replace image name of hass-configurator by ‘causticlab/hass-configurator-docker:x86_64’, that’s it.

version: '3'
services:
  homeassistant:
    container_name: hass
    image: homeassistant/home-assistant
    volumes:
      - ./hass-config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    network_mode: host
    depends_on:
      - mariadb
      - mosquitto

  mariadb:
    image: linuxserver/mariadb
    container_name: mariadb
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "${MYSQL_ROOT_PASSWORD}"
      MYSQL_DATABASE: ha_db
      MYSQL_USER: homeassistant
      MYSQL_PASSWORD: "${HA_MYSQL_PASSWORD}"
      PUID: 1000
      PGID: 1000
    volumes:
      - ./mariadb:/config
    ports:
      - "3306:3306"

  nodered:
    container_name: nodered
    image: nodered/node-red
    ports:
      - "1880:1880"
    volumes:
      - ./nodered:/data
    depends_on:
      - homeassistant
      - mosquitto
    environment:
      TZ: "Europe/Madrid"
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - "./mosquitto/config:/mosquitto/config"
      - "./mosquitto/data:/mosquitto/data"
      - "./mosquitto/log:/mosquitto/log"
    environment:
      - TZ=Europe/Madrid
    user: "${PUID}:${PGID}"

  hass-configurator:
    image: "causticlab/hass-configurator-docker:arm"
    container_name: hass-configurator
    restart: unless-stopped
    ports:
      - "3218:3218/tcp"
    depends_on:
      - homeassistant
    volumes:
      - "./configurator-config:/config"
      - "./hass-config:/hass-config"
    user: "${PUID}:${PGID}"

#  portainer:
#    ports:
#      - "9000:9000"
#    container_name: portainer
#    restart: unless-stopped
#    volumes:
#      - "/var/run/docker.sock:/var/run/docker.sock"
#      - "./portainer/portainer_data:/data"
#    image: portainer/portainer-ce

Now it is time to execute our compose file in order to create and run our services, so type ‘docker-compose up -d’ from the hass directory and the process will start, downloading images, creating containers and so on. After a while you will be presented the Home Assistant onboarding page in the url ‘http://<hostip>:8123’

If you are migrating from an older Home Assistant installation, you should copy over the content of your old configuration directory, including hidden files and folders, to the hass-config folder. Probably you will need to make some adjustments to your configuration, but it should work as expected.

Node-RED configuration

In order for Node-RED to be fully functional, further configuration should be done in Node-RED itself. From inside Home Assistant, click the Node-RED icon in the left bar.

• Add Home Assistant nodes to Node-RED: From the Node-RED menu on the top right bar select ‘Manage palette’, then in the install tab search for ‘node-red-contrib-home-assistant-websocket’ and install the module.
• Configure the mqtt broker: After putting an input or output mqtt node on a flow, you will be able to configure the mqtt broker in Node-RED editing the server field of the node. More info here.
• Configure connexion with Home Assistant: You need to edit an Events: all node on your workspace and fill the Home Assistant url and the access token. Information about this and how to generate an access token in Home Assistant can be found here.

NOTE: Node-RED should be restarted for this configurations to take effect. To restart the Node-RED container execute ‘docker restart nodered’

Portainer

As you can see, portainer service is commented at the end of the compose file. Should you need it, create the directory ‘./portainer/portainer_data’, uncomment the service in docker-compose.yaml and run ‘docker-compose up -d portainer’ to create the container. After this, you can access portainer on the url ‘http://<hostip>:9000’, then you should create a password for the admin user and select ‘Manage the local Docker environment’ in the next screen. Click on Connect and you are done, enjoy it.

Conclusion

We have seen how to install Home Assistant and some other components under docker using docker-compose. We will be improving this stack in next articles. If you have any question, leave a comment.