← Back to Blog Home

How to Run Home Assistant via LinuxServer.io’s Docker Image

Extracurricular Activities
by: Matt Fletcher
Home Assistant logo

Article summary

Home Assistant is a phenomenal tool for home automation. Although it can help across a variety of dimensions, I personally use it for muxing disparate tools and protocols like Z-Wave, HomeKit, Philips Hue, Lutron Caséta, etc. Bringing everything into one interface means I can control everything with HomeKit. This post is about how I set it up using LinuxServer.io’s image.

This is my seventh post documenting containers I use at home. You can also read about how I run the Unifi controller, how I run Plex, how I update DuckDNS, how I run Duplicacy., how I run Heimdall, and how I run Librespeed.

About LinuxServer.io

LinuxServer.io describes their organization as:

A group of like-minded enthusiasts from across the world who build and maintain the largest collection of Docker images on the web. At our core are the principles behind Free and Open Source Software. Our primary goal is to provide easy-to-use and streamlined Docker images with clear and concise documentation.

I’ve been using LinuxServer.io images for a couple of years. That’s because they’re easy to use, clear, and concisely documented. I tend to check here first when I need a new image.

Running the image via docker-compose

LinuxServer.io only officially supports running image via docker run or, preferably, docker-compose. Historically, I’d tinkered with Portainer — understanding the risks — and ultimately concluded it isn’t worth the effort. I like Portainer as a dashboard view, but as a management tool, it’s pretty blah. So, back to docker-compose I go.

Here is what the relevant section of my docker-compose.yml file looks like:


version: '3.7'

services:
  home-assistant:
    container_name: home-assistant
    image: ghcr.io/linuxserver/homeassistant:2021.8.7-ls35
    network_mode: host
    restart: unless-stopped

    devices:
      - /dev/aeotec-zwave-stick:/zwaveusbstick
    env_file:
      - ./common.env
      - ./secret.env
    volumes:
      - /mnt/service-data/home-assistant:/config

A few comments on the above:

  • I prefer to pin my image to specific versions, hence the explicit tag called out on the image line.
  • Home Assistant strongly recommends using host networking mode. I believe it can work in bridge mode, but Home Assistant won’t be able to automatically discover devices. I’ll use host mode for as long as I can get away with it.
  • The devices: section is passing my hardware Aeotec Z-Wave USB stick through to the docker container as /zwaveusbstick. Yes, you guessed right: this is for the Home Assistant Z-Wave component to be able to communicate with my Z-Wave devices.
  • The common.env environment file contains the standard LinuxServer.io environment variables used across all images: PUID, PGID, and TZ.
  • Lastly, the volume mapping makes my persistent data on the host system available as /config in the container.

Regarding host network mode

One thing that makes me nervous about host networking mode is port conflicts with other images. Right now I’m running about eight images, and, thankfully, the only port conflicts I have are for ports the other images don’t really need to operate effectively. But my Spidey sense is telling me that one day I’ll have an irreconcilable conflict.

I think when that happens I’ll need to make a new virtual machine dedicated to running Home Assistant only. This won’t be hard, and I can make it a small VM, but it will still be a nuisance. I’ll cross that bridge when I come to it.

Final thoughts on LinuxServer’s image

I’m quite thrilled with how well this image is running. Before the LinuxServer.io image, I did have one that worked, but I overall prefer the LinuxServer.io conventions, especially concerning user and group permissions. Big thanks to these teams for making such wonderful images and tools available to us.

Related Posts