Thibault Maekelbergh

🏡 Set up Home Assistant on macOS using Docker Compose

I love Home Assistant and very much like to spend time to contribute to this platform. Unfortunately my knowlegde of Python, the ecosystem and its tools is rather limited.

Trying to get things set up with pip, pyenv, virtualenv is very confusing coming from the Node.js world. So I decided to give it a go using Docker and using Docker-Compose to not having to type difficult CLI commands in each time.


First, of course, make sure you have Docker and docker-compose installed. If you use Docker for Mac those requirements will both be satisfied:

$ brew cask install docker
# Optional but recommended if you're gonna use docker/docker-compose in the terminal
$ brew install docker-completion

Using docker-compose

With Docker now set up we need a compose YAML file which we can spin up or down. Home Assistant documentation tries to outline this but I found that their summary was rather confusing and needed some extra work. Below is the compose file you can use. It will use a config folder next to where you store the docker-compose.yml file as a locally mapped volume which will hold all the Home Assistant configuration where you can dabble with your code:

version: '3'
container_name: home-assistant
image: homeassistant/home-assistant
# This is the required way to set a timezone on macOS and differs from the Linux compose file
- TZ=Europe/Brussels
- ./config:/config
restart: always
# Also required for macOS since the network directive in docker-compose does not work
- "8123:8123"
# Add this or docker-compose will complain that it did not find the key for locally mapped volume

Starting Home Assistant

Now if you navigate to your folder in terminal you can quickly spin up a Home Assitant instance:

$ ls -l
drwxr-xr-x 16 thibaultmaekelbergh staff 512 Nov 6 20:37 config
-rw-r--r--@ 1 thibaultmaekelbergh staff 269 Nov 6 19:27 docker-compose.yml
$ docker-compose up -d
Creating home-assistant ... done

Now if you navigate to http://localhost:8123 you should be able to set your login details and see your Home Assistant instance! You can now make changes to configuration.yaml and use docker-compose restart to restart the container and have your changes visible in the application.

Sidenote: I actually prefer using Kitematic for this since it shows me the log output which is very useful for Home Assistant!