In the current post series, I’m describing the path I took from a regular Home Assistant setup on Home Assistant Blue to a home server with Docker and various software. Assuming we already have ODROID-N2+ with Debian Buster and Docker setup, our next step would be bringing Home Assistant with MariaDB to life.
Previous posts in series:
- Debian Buster on ODROID-N2+ aka Home Assistant Blue
- Installing Docker on ODROID-N2+ with Debian Buster
Docker Compose allows us to define and run multi-image applications with one simple YAML file and one command. Home Assistant is sure could be a multi-image application, because at least we need a good solution for history and stats. Later on, we will add ESPHome, Zigbee2MQTT, and other services, but in today’s post let’s focus on a Home Assistant itself.
I don’t want to drop my
docker-compose.yml here and mind my own business. There are a lot of examples around the Internet, but most of them have questionable configuration entries. I want to explain, why and when you need to use one or another docker settings.
Host network mode for example. Official Home Assistant documentation suggests using
network_mode: host not mentioning, that it would be a good practice only when your Home Assistant is the only container in your smart home setup. When we have several containers that should communicate with each other, we sure need to use
network_mode: bridge. First of all, it would follow official docker docs. Second, it will allow us to use container names instead of IP addresses (that could be changed) when integrating our additional services into HA.
Also, why Home Assistant needs a privileged mode? Exposing your operating system to a service that could potentially be accessed from the outside of your router sounds like a very bad idea. Not gonna lie, this would be the easiest way to start using Home Assistant in a Docker: host network mode and privileged execution. But you can avoid potential risks and issues in the future just by understanding slightly more complex configuration options.
The most comfortable way to edit files, execute commands, and do any other things with your headless (which means a computer without a monitor) server is to use Visual Studio Code with the “Remote – SSH” plugin.
Now it is time to drop my
docker-compose.yml and describe some more things on a working example:
As I’m using my server as a root user, my home directory is
/root. I’ve placed
/root and have a separate folder for each smart home stack service. I’ve created the
/root/homeassistant/config directory for Home Assistant configuration, and
/root/homeassistant/share for the HA share folder. “share” folder is not necessary. I created it only because I had an integration that stores a file in the “share” folder. You can create “media” and any other folders the same way if you need it.
So, obviously, these lines in
homeassistant service are for exposing host folders to a Home Assistant container:
Let’s get back to the
mariadb service for now. The
ports allow us to expose network ports for inbound connections. 3306 is a standard MariaDB port. HA will use it for connection.
MARIADB_ROOT_PASSWORD is a root password for your MariaDB installation.
MARIADB_DATABASE variable would force MariaDB to create a database with a given name upon a first start, assigning
MARIADB_PASSWORD to it. You will need this data for the Home Assistant configuration later.
Going back to the
homeassistant service, let us look to other options:
You should replace “Europe/Kyiv” with your timezone name taken from the “TZ database name” column in the table here.
This will pull the latest stable Home Assistant version from packages on GitHub but only when you’ll tell Docker Compose to do so. Stopping and starting the container will not pull any images.
To get more control over Home Assistant versions you can replace
latest with a given package tag found here. For example:
Now you’ll be sure that Home Assistant will not be updated until you update your
This is the only port you need to expose to make Home Assistant work even through Nabu Casa Cloud.
This is how you allow a given hardware from your host machine to be used in Home Assistant.
/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 – is a GSM modem, connected to my host machine.
/dev/ttyACM1 – is a path to a device I’m using in Home Assistant when adding GMS modem integration.
These lines will tell Docker that when the Home Assistant container is starting, it should wait till MariaDB will be up first. Otherwise Recorder component in Home Assistant will fail to start and you’ll get Home Assistant without entities history.
Now it is time to fire things up with:
docker compose up -d
You should execute this command in the same folder where your
docker-compose.yml is placed.
This will download all the necessary data to start your Home Assistant. Once done, you should be able to navigate to your Home Assistant frontend using your server’s IP address and port 8123. For example “http://192.168.90.23:8123” from inside your local network.
Now we need to configure the
recorder component in the newly created
configuration.yaml file. In my case, it is created under
The database URL is consist of mysql://MARIADB_USER:MARIADB_PASSWORD@mariadb/MARIADB_DATABASE?charset=utf8mb4
“mariadb” in the URL is the name of our service from
Stopping, starting and restarting
Now we need to restart Home Assistant for changes to apply. We can easily do this with:
docker compose restart homeassistant
Sure you can do the same from Home Assistant UI as usual.
While you have several services defined in your
docker compose restart
without any additional parameters will restart all services. Also, you can just
stop any container or
docker compose start mariadb
Or stop it all:
docker compose stop
Not sure why you’ll want to update your MariaDB container while it works, but updating Home Assistant is important.
If you are using
latest tag for your
homeassistant service image:
to update it to a latest stable version you’ll need to:
docker compose pull homeassistant
docker compose up -d homeassistant
Don’t forget to change the image tag if you are not using
Next posts in series: