This is a cautionary and true story about my Home Assistant + Docker setup.

Home Assistant is an open source platform that’s a lot of DIY fun to transform your home or apartment into a lean mean, automated space.

Docker is an open source tool (and company by the same name) used to simplify and scale application deployments across any OS environment. More about both in a moment.

A few weeks ago, I found myself in a position that most people have experienced at some point. I sat down and logged on to my computer. I just wanted  to access Home Assistant, as I had done so many times before. Only this time, it was different.

Instead of seeing the familiar black and white front end of my home control platform, I was greeted by an ugly 502 error.

After a brief moment of panic, I began working backwards. Trying in vain to retrace my steps in the hopes of identifying when and what caused my system to fail.


I checked all the logs.

I reviewed recent Home Assistant + other Docker containers automatically updated via Watchtower to sniff out a breaking change.

To this day, I still don’t know what happened. The most infuriating part of it was I thought I did everything right. I synced backups regularly to GitHub and locally via Syncthing. I kept Ubuntu up to date and was generally on point. I was a good boy.

That afternoon I spent a few hours becoming increasingly frustrated until I reached the breaking point and went with the nuclear option: starting from scratch with Home Assistant & Docker.


This time, I would backup my entire Docker setup, not just the Home Assistant folder.

I would implement versioning with Syncthing and expand it to other devices in my network to improve resiliency. Finally, I was convinced to spend the few extra minutes getting my docker-compose file on point instead of taking it easy with Portainer.

All things considered, I learned some valuable lessons.

I became more familiar with the tech I had previously just taken for granted. Perhaps more importantly, I actually heeded the sage advice given freely by the wiser and more experienced. Resiliency and redundancy were now intentional rather than afterthoughts.

The end result was a more streamlined, resilient, and responsive home automation system that I’m sharing with you today.


Alright, enough melodrama. Here’s what I actually did to (literally) get the lights back on.

I was bored of Ubuntu and looking for something more streamlined, whatever that means. After reading over options, I went with Linux Mint.

The simple UI appealed to me and it played nice with the Intel NUC I use as a dedicate home automation device. Yes, I could have gotten away with something more stripped down like Ubuntu server or any number of other options but this is my blog and I went with Linux Mint.


I first learned about Docker and the concept of containers through previous home automation adventures.

In a nutshell, a “container” acts as a stand alone app that run across any operating system. The container takes care of all OS dependencies and other quirks that might otherwise cause problems. This is different than a virtual machine, which generally simulates an OS that has apps layered on top of it.

Yes, it’s a gross oversimplification. There’s thousands of videos and articles explaining it more in depth. Here’s a quick article if you want to know more.

Anyways…  I added Docker CE (community edition) following the instructions outlined here.

Next, I followed these steps to install Docker Compose. Docker Compose is a great tool that enables rapid management of multiple containers. I’ve found this tool immensely helpful as the number of containers in my smart home system increase. If you’re already using Home Assistant, you’re painfully aware of YAML.

That’s good because that’s also how Docker Compose files are written.


Quick recap of what’s happened so far in this tale:

  • Fresh install of Linux Mint + a few cycles of updates to keep things safe and smooth
  • Installed Docker Engine (or if you’re using Ubuntu)
  • Installed Docker Compose

This is where I started to incorporate my previous failures to build a better system.

Before, I’d probably have just pulled the Home Assistant container and immediately started turning lights on and off. But post-disaster, I’m starting to learn (the hard way).

I set to work with the help and guidance of the always fantastic Home Assistant community. Remote access to Home Assistant is a must for my household and it needs to be secured.

There’s at least two ways of securing Home Assistant:

  1. SSL
  2. Reverse proxy

I went with #2 using the Let’s Encrypt container which also includes a NGNIX reverse proxy server. You can find instructions on how to get that working if you’re interested here.

EDIT: Some time after writing this, I ended up going with Caddy, a super lightweight web server that made it even easier to secure all my Docker containers.


At this point, I had a semi-respectable docker-compose.yaml file.

My go-to containers include:

  • Home Assistant container for the home control and home automation
  • Portainer to help mange containers on the fly through a simple UI
  • Watchtower to keep containers updates automatically.
  • Node Red for visual automatons because let’s face it, writing YAML automatons sucks. Don’t believe me? Good luck finding that extra space causing your Home Assistant instance not to load…
  • Lets Encrypt to securely handle reverse proxy duties and automatically renew certs. Caddy
  • HA Dockermon to allow Home Assistant to control other containers.
  • Plex for home media server
  • Influx DB + Grafana for cool looking dashboards based on the data generated by Home Assistant and connected devices
  • Syncthing to backup persistent container volumes and the docker-compose.yaml across local devices. If you’re getting a permission sync error like I was, try adding an empty file name <code>.stfolder</code> to the directory you want to sync. Full issue details documented here.

All of these are configured in the docker-compose.yaml file. I can start or stop all of these containers with the single command: docker-compose up -d

Once running, all the various services are managed through the single Organizr interface.

The great thing about containers is the speed at which you can try out new ones. A simple deploy takes seconds and if you don’t like or find something better, just kill it and pull something else. Instead of constantly needing to install new libraries and dependencies, you just deploy the container, define where you want persistent data to be stored (if applicable), and it manages the rest.


Shame on you.

Wrapping things up:

  • Something broke somewhere and I couldn’t use Home Assistant anymore. I was in the dark for a few days.
  • I started from scratch and actually followed what smart people suggested to build a better, more resilient system.
  • Home Assistant + Docker setup 2.0 is running like a dream and I sleep better at night as a result. I can also turn on lights again which is a plus.

That’s it, there’s not always a profound lesson to be learned in every post. Sometimes they just, sort of, end.