Update 2024-06-04: updated the guide for the "new" year.
Finally, a Raspberry Pi 4 with 8GB RAM came into stock that wasn't outrageously priced.
Quick tip: remember where you've placed your Micro SD card from your last bricked Pi so you don't have to wait for the delivery of a new one.
I'm assuming you have basic knowledge of Linux (for example, how to connect to another computer with SSH), so forgive me if I don't explain everything down to the last detail. Don't hesitate to message me on X if you have any queries 🙂.
We'll follow these steps to get a working installation of Home Assistant running on your local network:
While I'm not typically a fan of installers, preferring to understand what's happening during each step, I highly recommend using the Imager tool for installing Raspberry Pi OS on your SD card in this instance. It saves time and prevents headaches during the initial configuration.
Download Raspberry Pi Imager for your operating system.
Screenshot of the home screen of Raspberry Pi Imager
Screenshot of the advanced options of Raspberry Pi Imager
I customised a few things:
Remember to press Save before proceeding. You are now ready to write everything to your SD card, which may take a few minutes depending on its speed.
Once complete, insert the card into your Raspberry Pi and continue.
After inserting the SD card, power up your Pi by connecting the power supply. Allow it 1 or 2 minutes to fully boot.
You can then connect using your preferred terminal:
ssh pi@rpi.local
Change the username (pi
) and hostname (rpi
) according to what you selected in the options dialogue. Alternatively, use the IP address assigned by your router.
To update packages and upgrade your Pi to the latest version, run:
sudo apt update && sudo apt full-upgrade
Important: Ensure you reboot before continuing. This isn't optional; skipping this step will likely result in Docker installation failure.
sudo reboot
Your Pi will reboot, ready for the next step.
We'll use Docker's straightforward install script. The following command is all that's needed:
curl -sSL https://get.docker.com | sh
By default, non-root users don't have rights to run containers, so we'll add our current user (pi
) to the docker
user group, eliminating the need for sudo
every time we want to run a container.
sudo usermod -aG docker ${USER}
Run groups ${USER}
to verify that this has worked. You should see the user group you just added at the end of the line.
I highly recommend enabling the Docker system service. This ensures Docker automatically starts whenever you reboot your system and will also start containers configured with a restart-policy of always
or unless-stopped.
We'll configure our Home Assistant container in this way.
Enable the Docker system service by running:
sudo systemctl enable docker
Finally, we're at the stage of running Home Assistant in a Docker container accessible from your local network.
Create a file called docker-compose.yml
in a folder called docker/homeAssistant
within your home folder, resulting in this structure:
pi@rpi:~ $ tree -L 3.└── docker └── homeAssistant └── docker-compose.yml 2 directories, 1 file
Input the following into the docker-compose.yml
file. You'll likely need to change the timezone to match yours. If you've used a different directory structure, adjust your volumes configuration accordingly.
---version: '2.1'services: homeassistant: image: lscr.io/linuxserver/homeassistant container_name: homeassistant network_mode: host environment: - PUID=1000 - PGID=1000 - TZ=Europe/Berlin volumes: - /home/pi/docker/homeAssistant/data:/config restart: unless-stopped
The last option, restart: unless-stopped
, ensures our container reboots after restarting your Pi unless you've manually stopped it.
In theory, you're now ready to start your container and begin configuring Home Assistant.
From the directory /home/pi/docker/homeAssistant
, run:
sudo docker compose up -d
The -d
flag runs the container in detached
mode in the background.
If you see no errors appear, congratulations! Access Home Assistant's management backend by navigating to http://rpi.local:8123
(Adjust URL according to your hostname if different). You can now start the onboarding process; for this, I highly recommend referring to the official documentation.
I hope this post helped you! If you have any questions, hit me up on X 😊.
You might find these related articles helpful or interesting, make sure to check them out!