Docker is the unfortunate future

Gotchas when configuring Home Assistant on Docker on Windows

This post was most recently updated on August 31st, 2022.

3 min read.

What a nice headline, right? 😅 One day, I thought I’d give Home Assistant a try! And obviously, I couldn’t just make things easy and run it in a Linux virtual machine or my Raspberry Pi – instead, obviously, I decided to run it on Windows 10! And obviously, I’d use Docker for it. And of course, not just Docker, but docker-compose.

Whatever that is. I don’t know – it’s the first time I’m trying out Docker. Or Home Assistant! Another learning experience coming in, am I right? 😁

Anyway, just as usual, let me document the pitfalls I run into – so that you won’t need to!

Tips on getting Home Assistant running on Docker on Windows 10

My tips for getting this stuff up and running.

Docker has a strict version requirement on Windows 10 – and not all hardware work on recent enough operating system versions!

I grabbed an old laptop to serve as my Docker host. That was my first mistake.

Since Docker requires Windows 10 version that supports Hyper-V and Containers features – they’ve been supported on Windows 10 Home 2004 and built 16299 on Windows 10 Pro, Enterprise, and Education (“Fall Creators Update”, October 2017).

Apparently, a HP machine from 2011 can’t handle Windows 10 Home 2004. But it COULD handle a 2017 version of Windows 10 Enterprise! After an upgrade, I was good to do!

Note: Check out the requirements for your Windows Operating System.

Home Assistant on Docker on Windows 10 requires:

  • Windows 10 Home 2004 or
  • Windows 10 Pro, Enterprise or Education build 16299 (“Fall Creators Update”, October 2017)

Beware of the Network_mode!

If I knew how to read, I would’ve known this one, because it was in fact documented. When you’re creating your docker-compose.yml file, you should be following a guide like this.

Now, at the top of the page, it’ll say this:

These below instructions are for an installation of Home Assistant Core running in your own Docker environment, which you manage yourself.  Note that Docker command line option --net=host or the compose file equivalent network_mode: host must be used to put Home Assistant on the host’s network, otherwise certain functionality - including mDNS and UPnP - will break. The -p command line option or the compose file equivalent ports: is not compatible with host networking mode and must not be used.
Warning against setting ports for your docker container. Ignore this.

You need to ignore this because on Windows you can’t use “host” network mode. It’s not available. On a side note, I think it’s because Windows is so much more secure than macOS or Linux… Right? 😉

It actually says in the Windows section:

Host networking is not supported on Windows so we have to forward the port 8123. This will let you access your Home Assistant portal from http://localhost:8123, and if you forward port 8123 on your router to your machine IP, the traffic will be forwarded on through to the Docker container.

Anyway, here’s my docker-compose.yml file:

version: '3'
    container_name: home-assistant
    image: homeassistant/home-assistant:stable
    #network_mode: host # This won't work on Windows...
      - C:/Path/To/Your/HomeAssistantConfiguration/HomeAssistant:/config # Shares the configuration directory
      - TZ=Europe/Helsinki #
    restart: always
      - 8123:8123 # this is the important part!

Note: Using an explicitly defined port, you might break run into issues. Or not. The documentation is kind of murky, but there are some older conversations describing issues with Multicast and device discovery. So.. Beware, I suppose, but I don’t yet know of another way to get this working.

Use OneDrive to version your configuration and Home Assistant files!

Ah – not sure if this will cause side effects down the line. But so far, so good!

You don’t need to do this. But since you will be maintaining the Home Assistant files from a folder in the host system mounted to the container, and you might need to make some changes to those files, you will need to version control or back them up somehow.

Since I’m lazy and don’t know of any downsides, this is what I did:

The first folder contains the docker-compose.yml (and is used as the configuration when running docker-compose on the host), and the second folder contains the Home Assistant files.

The firewall will block you from accessing Home Assistant outside the host

If you want to access Home Assistant from outside the host (and you probably do), you need to open your Windows Defender Firewall and whip up a new rule allowing inbound traffic to port 8123 using TCP.

I haven’t yet exposed my installation to the outside world – that’ll probably require a whole other post in itself.

Things you should probably install on Home Assistant

In this section, I’ll document things I’ve found that probably will benefit any Home Assistant installation.

This is by no means an exhaustive list – I’ll update it as need be.

  • HACS

Okay, that’s really short for now. Sorry.

Anyway, that’s all I had for now! Look forward to updates to this post :)


5 4 votes
Article Rating
Notify of

Inline Feedbacks
View all comments