In this guide, we will install and configure the Home Assistant companion app for macOS.
Today, I have a newly updated guide on getting started with Home Assistant. We’re going to go over the devices we can use, the installation process, and the initial configuration. We will also cover a few must-have add-ons and integrations that you should add after installing Home Assistance.
Table of Contents
You can install Home Assistant on almost any device out there—for example, an old laptop, a Raspberry Pi, or a NAS server like Unraid. There are also different installation methods. You can install the Core version of Home Assistant on a Docker container or Linux. The other method is to install the OS version on a Raspberry Pi or a virtual machine. The Core version does require more steps to configure, updating and also installing different integrations. However, the Home Assistant OS version is an all-in-one solution. It comes with a supervisor, making it easier to update Home Assistant, create snapshots and install different add-ons.
Best version to install and device to use
When starting with Home Assistant, the OS version is definitely the way to go, and a Raspberry Pi is also a good device to start with. It is small, cheap and it has low power consumption. So, for this guide, I’m going to show you how to set up the OS version on a Raspberry Pi. However, if you are looking to set up Home Assistant on a Ubuntu server, a Proxmox machine, or an Unraid NAS server, I have tutorials for that as well.
- How to set up Home Assistant in Docker and in an Ubuntu server
- Install Proxmox and virtualize Home Assistant
- How to set up Home Assistant on Unraid
Flash the Home Assistant image on an SD card
To start, you’ll need an SD card that is at least 32 GB, and you can use Balena Etcher to install the Home Assistant Image on the SD card. So, connect the SD card to your computer and get the URL for the image via home-assistant.io/installation/raspberrypi. Select the 64-bit version for the Raspberry Pi that you have, and copy the URL for the image. After that, open Balena Etcher, select Flash from URL, enter the URL for the image, and click OK. Then, click on Select target, select the Micro SD card and then click on Select. Lastly, click on Flash and give it a minute for the process to finish.
Once the process completes, remove the SD card from the computer and connect it to the Raspberry Pi. Then, connect the Raspberry Pi to your router with an Ethernet cable and boot it up. The Home Assistant OS will start downloading the latest version of Home Assistant. To access the web interface, open your browser and go to homeassistant.local:8123. Once the setup is completed, you can start with the initial configuration.
On the first step, create a new administrator account to access the web interface. So, enter a name, username, password and click on Create Account. For step 2, You can set up a custom name for your Home Assistant. Also, set up the location, time zone, and unit system. Click on Next, and for step 3, Home Assistant auto-discovers the smart home devices connected to the home network. You can then add them and set them up into rooms. Click on Finish, and the Home Assistant web interface comes up.
If you still need to integrate more devices or online services, you can do so by going to Configurations, Integrations, and then click on Add integration. Some integrations are not yet available to set up directly from the web interface, so if you don’t find the specific device or service, you can check all the supported integrations by going to home-assistant.io/integrations.
Use a naming convention for entities
One thing that is good practice to do before configuring the Home Assistant dashboard is to go over all your entities’ names. You want to create a naming convention that you can follow when naming your entities. This will make it easier to search for a specific entity and also to differentiate similar entities.
An entity’s name starts with the type of entity that it is, aka domain—for example, a switch, light, sensor, media_player, etc. Then, separated with a period, you would have the actual name of what the entity is for. A naming convention that a lot of us use is to add the room’s name, either abbreviated or just the initials, after the domain. For example:
light.br_floor_lamp, etc. Sometimes, you might also have 2 or more of the same device in a room, so you would also want to specify the position within that room. For example. if you have several lights, you could set it like,
light.lr_floor_lamp_back. You get the idea. So, thinking about a naming convention that works for you, it’s definitely good practice. You are definitely going to appreciate it later.
Accessing the UI Editor
To customize the dashboard, you can access the UI editor by clicking on the Menu icon on the top right and then Edit Dashboard. A pop-up comes up stating that Home Assistant automatically adds new entities to your dashboard. However, you want to customize it the way you want to. So, check the option Start with an empty dashboard and then click on Take Control.
To start adding your entities to the dashboard, you first need to add a View. Views are like tabs on a browser, and you can set up several Views in the Dashboard. To add a new one, click on the plus “+” icon on the top left. Set up a title for the view. You can also set up an icon if you want and then click on Save.
Home Assistant has several different cards that you can choose for your entities and organize the web interface the way you want. To add a new card, you can click on Add Card and select the type of card you would like.
Home Assistant Light and Dark theme configuration
A feature that I want to point out is that Home Assistant has both a light and a dark theme and it switches between the 2 automatically depending on your system preferences. However, if you want to set it to a specific mode, you can go into your Profile, and under Theme, you can change it from Auto to either light or Dark. In addition to that, you can also change the primary color and the accent color.
What’s next after installation?
Alright, so you have Home Assistant installed, and you configure the dashboard the way you wanted to; what’s next. There are a few must-have add-ons that you want to install in Home Assistant. The first one which is going to allow access to Home Assistant remotely is the Nginx Proxy Manager. This add-on will also need the Maria database, so install that add-on as well. On top of that, you need to set up a couple of things on your router settings. You need to assign a static IP address to your Home Assistant and then set up 2 port forwarding rules to forward port 80 and port 443 to Home Assistant.
Set up a static IP to Home Assistant via the web interface
To assign an IP address to Home Assistant, you can also do it from the Home Assistant web interface. But, I personally recommend having this setting configured on the router directly. If you want to set it up via Home Assistant. Go into Supervisor. System and under Host, click on Change next to the IP address. Next, on the pop-up that comes, click on IPv4 and change it from DHCP to Static IP. Save the changes and reboot the host, so the changes take effect. When you assign a new IP address to Home Assistant, you would need to reopen your instance using the new IP address.
Set up port forwarding rules
After you have the static IP address configured, locate the port forwarding settings in your router and add 2 rules with the following settings:
First forwarding rulePort: 80Forwarding IP: The Home Assistant IP addressForwarding Port: 80Protocol: TCPSecond forwarding rulePort: 443Forwarding IP: The Home Assistant IP addressForwarding Port: 443Protocol: TCP
With this configured, you can go ahead and set up the MariaDB and Nginx Proxy Manager add-ons.
Set up the MariaDB add-on
The first add-on to install is MariaDB. So, open Home Assistant, go into Supervisor, Add-on Store search for the MariaDB add-on, open it, and click on Install. Then go into Configuration and set up a username and a password. Under
rights, enter the same username and the
database, leave it set as
homeassistant. Save the changes, go back to the Info tab, and Start the add-on.
Set up the Nginx Proxy Manager add-on
After you have the MariaDB add-on setup, go back to the Add-on Store, search for Nginx Proxy Manager, open it and install it. After it is installed, Start the add-on and click on Open Web UI. To sign in for the first time, enter in the email field,
firstname.lastname@example.org. For the password enter
changeme. Sign in and a pop-up comes up for you to change the default credentials to something private.
Set up a DuckDNS subdomain
To set up the remote access, you first need to create a DuckDNS subdomain. Go to duckdns.org and log in using one of the available methods. Create a subdomain, and your new URL would be, subdomain.duckdns.org.
Go back to the Nginx Proxy manager, click on Hosts, Proxy Hosts, and then click on Add a Proxy Host. Under Domain Name, enter your DuckDNS URL. Then enter your Home Assistant IP address under Forward Hostname/IP. For the Forwarding Port, enter 8123. Enable the option Websockets Support and then go to the SSL tab. Under SSL Certificate, select Request a new SSL Certificate. Then, enable Force SSL, Enter your email under, Email address for Let’s Encrypt, and agree to the terms of service. Click on Save, and you should now be able to access your Home Assistant locally using the IP address or the hostname. And remotely using the DuckDNS URL.
Set up the Internal and External URL in Home Assistant
The last thing you need to do is set up the internal and external URL in the Home Assistant configuration. So, go back to Home Assistant, Click on Configuration, General and enter the following:
External URL: https://yoursubdomain.duckdns.org Internal URL: http://192.168.1.XX:8123
Set up the VS Code add-on
The next add-on that you want to add to Home Assistant is VS Code. With this add-on, you can manage your Home Assistant configuration files directly on a browser and from any device. The add-on does use a lot more resources, so it’s recommended to install it in a Raspberry Pi with at least 4 GB of RAM.
To install it, go back to Supervisor, Add-on Store, search for Visual Studio Code, click on it and then install it. To easily access the add-on, you can toggle the option Show in sidebar. Start the add-on, then click on Open web UI, and you now have access to the Home Assistant configuration files.
Set up the Samba Share add-on
If you rather use VS Code on your computer you can do that and access the Home Assistant configuration files. To do that, you’ll need to install Samba Share, which is another must-have add-on in Home Assistant. In the Add-on Store, search for Samba Share. Click on it and install it. When the installation completes, go to Configuration and set up a
password. Click on Save, go back to the Info tab, and Start the add-on.
To access the Home Assistant files on your computer, open your file explorer, and on the search bar on the top, enter
\\homeassistant\config, or you can also enter the Home Assistant IP address instead of the hostname.
Other recommended add-on and integration
Another add-on that I recommend installing is the WireGuard add-on. WireGuard is a modern, open-source VPN protocol that you can use to connect from any public hotspot and have a secured connection to your home network. Also, if you use Google assistant either on your phone or a smart speaker, you can link Home Assistant to control your entities using your voice. You can check out the tutorial guide for each here:
- How to set up a secured VPN with WireGuard and Home Assistant
- How to integrate Google Assistant with Home Assistant without a subscription
The last thing that you want to do after you have Home Assistant all set is to create a snapshot of your setup. So, if something ever happens and you need to reinstall Home Assistant, you can easily recover your whole setup with that snapshot. To create one, go into Supervisor and then Snapshots. Set up a name for it, select if you want to create a full or a partial snapshot of your system, and you can also set up a password so when you try to restore from the snapshot, you would be required to enter the password to unlock it. After you have the snapshot created, you can click on it and download it so you can save it on your computer.