Home Assistant and ESPhome in Docker
Summary:
I will show step by step how to install and configure Home Assistant with ESPHome Server in Docker containers as the main service. I will install Home Assistant (no supervisor) as I don’t feel it is necessary to keep all the functionality I had in the Home Assistant Operating System on my Raspberry Pi 4. Also, it is one of the recommended methods in Home Assistant Alternative Installations . Important! Installing Home Assistant OS Supervisor on a container with an operating system running, for example: Ubuntu, is not currently recommended and would increase the resource consumption of our server unnecessarily. We must bear in mind that in a server we must be as efficient as possible for different reasons such as: energy efficiency, stability, durability, compatibility, among others.
Recommendations:
- Have knowledge of the operation of Home Assistant as in its configuration.
- Have knowledge in the use, configuration and operation of ESPHome.
- Have knowledge of Docker.
- Have knowledge in ssh, in bash. Well, basically everything you need to be able to manage a server and these specific services.
- I recommend having knowledge of online text editors such as Vim. But it is not essential. The essential thing is that you know how to communicate with your server and edit the files. This can be FTP server, Visual Studio Code over SSH, or whatever method you prefer.
Introduction:
By setting up a server at home I realized that I could unify all my services on a single computer using containers.
Why Home Assistant on a server?
Keep in mind that Raspberry Pi is an excellent solution for a myriad of projects. So much so that it is the standard and recommended method by Home Assistant and that I must recognize; It works perfectly on this board. In addition, and not a minor fact, it is a very, very efficient hardware.
But unfortunately it is not scalable and that makes it more susceptible to the passage of time. As is, for example, the use of flash memories. Although today they are getting better, they are still inferior to the technologies that we can apply to a tower. Because in my server tower, I have more power, resources are not an issue here. So much in processing, which translates into the speed of my assistant. As in storage that translates into the most stable and extensive databases.
Why Home Assistant in Docker?
First, because Docker is an open source project that automates the deployment of applications within the most popular software containers today. It is supported by Home Assistant and not least: there is a lot of documentation.
Also due to the characteristics of the use of containers, such as: potability, simplicity to upload, download, duplicate, support and experiment with services with low risk and high flexibility. Among many other benefits of the world of containers.
Think, in my case: On a single server I have Home Assistant, ESPHome, Unify Controller, Nextcloud and web’s among others.
Step by step Home Assistant:
Everything stated here refers to my experience to a server running Ubuntu Server with Docker.
ports:
It is important that you manage your firewall well and take into account which posts you must open. Let’s start with the minimum for main functionalities and that you should not forget.
sudo ufw allow 8123
sudo ufw allow 6052
install Home Assistant on docker:
As easy as creating a .yml file in a specific directory for example, let’s try one, keep in mind that my_user is your directory and you must have the necessary read and write permissions:
#in your working directory example /home/my_user/
mkdir -p dockercompose_backups/homeassistant/ && mkdir -p dockercompose_backups/esphome/
We create a file for docker compose:
#in your working directory example /home/my_user/
vim /home/my_user/dockercompose_backups/homeassistant/docker-compose.yml
Note: You know that you can use the text editor of your choice.
Inside this file we paste:
version: '3'
services:
homeassistant:
container_name: homeassistant
image: "ghcr.io/home-assistant/home-assistant:stable"
volumes:
- /PATH_TO_YOUR_CONFIG:/config
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
privileged: true
network_mode: host
/PATH_TO_YOUR_CONFIG is the directory where we must mount the root volume of our Home Assistant. This is where our setup will be. It is a directory that we should always back up with Rsync for example.
Then we save. For example suppose that in the docker-compose.yml we put the line in volumes: similar to this:
- /home/my_user/homeassistant/config:/config
There we will have to paste our Home Assistant files, the configuration that comes from our Raspberry Pi.
Note: We haven’t started the container.
Restore Home Assistant:
I am going to describe according to my experience, which was the fastest method to move my complete and quite extensive configuration from my Rasberry Pi to my Home Assistant Docker. Since to date the official image for Docker does not allow restoring with the classic steps, although it tentatively allows us to create snapshots.
Backup:
To start we must have our backup image created in Home Assistant OS from Rasberry Pi. This will be a .tar file. Preferably when we make the snapshot we avoid including the extensions, since they will not be of any use to us in Docker. Note: To avoid errors, it is better to have our Home Assistant to the latest version on the Rasberry Pi. Then when we have our example backup: backup.tar on our personal computer. We unzip it.
- We look inside this and we will have a compressed file called: homeassistant.tar.gz
- We unzip this and inside we will have a directory called data. Ualá, there is all our configuration.
- We change the name of “data” to “config”.
- We create the directory where our volume will be. That is, the directory set in the “docker-compose.yml”. For the example it would be:
#in your working directory example /home/my_user/
mkdir homeassistant
- We send our brand new config folder inside the homeassistant directory we just created. That is, we must have the following: /home/my_user/homeassistant/config Where config will have all the content we had in data. Try to use a reliable transfer method. And don’t forget that inside config there are hidden directories and files that you should also transfer. I used FTP over TLS in FileZilla.
Start Home Assistant container:
Finally we start our container:
cd /dockercompose_backups/homeassistant/
docker-compose up -d
#It could also be depending on the version of docker compose.
docker compose up -d
Everything should be working if we do everything correctly. Home Assistantant will be at:
- IP_server:8123
When launching the container with the configuration that we had on the Raspberry Pi, it could indicate an error in the logs that we will discuss at the end.
Step by step ESPHome:
Backup ESPhome:
In our Home Assistant OS on the Raspberry Pi and by using the app for example “File Editor” we download all the .yaml files inside the esphome folder. Each of these .yaml must represent a device. eg: my_node.yaml Let’s not forget to download the file: secrets.yaml and if we have a directory with fonts and/or images. We put everything inside a directory called config on our personal computer.
Now on our server we create a directory for the ESPHome configuration as we did with Home Assistant:
#in your working directory example /home/my_user/
mkdir esphome
As in the case of Home Assistant we must put the config folder that contains all our configuration files for each node, secrets and others inside the esphome directory on the server. That is, we must have the following:
/home/my_user/esphome/config
We start ESPHome container:
We create a file for docker, compose following the example:
#in your working directory example /home/my_user/
vim /home/my_user/dockercompose_backups/esphome/docker-compose.yml
Inside this file we paste:
version: '3'
services:
esphome:
container_name: esphome
image: esphome/esphome
volumes:
- /path/to/esphome/config:/config
- /etc/localtime:/etc/localtime:ro
restart: always
privileged: true
network_mode: host
/path/to/esphome/config is the directory where we must mount the config volume of our ESPHOME. Now this will be where our configuration will always be.
Save the docker compose file.
source: Getting Started with the ESPHome Command Line
For example suppose that in the docker-compose.yml we put the line in volumes: similar to this:
- /home/my_user/esphome/config:/config
There we will have all the configuration that comes from our Raspberry Pi from our ESPHome.
Finally we start our second container:
cd /dockercompose_backups/esphome/
docker-compose up -d
#It could also be depending on the version of docker compose.
docker compose up -d
Update nodes:
Once our EspHome Server is installed and configured. We can find the dashboard at:
- IP_server:6052
If everything went well there we should find our connected devices. And surely pending an update.
Bux fixies:
After starting my container with Home Assistant I found some errors in the log.
A resolution:
- Stop Home Assistant:
docker container stop homeassistant
- In the folder .storage, find the file: core.config_entries
you have a backup the config files? - Now delete de nexts lines:
{
"entry_id": "your_id",
"version": 1,
"domain": "raspberry_pi",
"title": "Raspberry Pi",
"data": {},
"options": {},
"pref_disable_new_entities": false,
"pref_disable_polling": false,
"source": "system",
"unique_id": null,
"disabled_by": null
},
- Start the container
docker container start homeassistant
Great! that worked for me.
