HomeAssistant: Solving Home Assistant Setup Issues with Nginx Reverse Proxy

Struggled with setting up Home Assistant behind Nginx? Discover solutions for WebUI access, configuration complexities, and WebSocket handling in my detailed troubleshooting guide. Perfect for home automation enthusiasts!

HomeAssistant: Reverse Proxy with Nginx — two issues I faced

Intro

Over the 4th of July long weekend, I set a personal goal to bring up Home Assistant, an open-source home automation platform. I anticipated a straightforward setup, but I encountered three significant issues while configuring it with Nginx as a reverse proxy. Here’s a detailed account of the challenges and solutions I discovered.

First Issue: Unable to Open WebUI

To start, I used a basic docker-compose file to bring up Home Assistant. Although the docker-compose command executed without errors, I was unable to access the WebUI. This was puzzling because I expected the WebUI to be readily accessible once the container was running.

version: '3.8'

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=YOUR_TIME_ZONE
    restart: unless-stopped
    network_mode: host

After some investigation, I learned that the network_mode=host setting is not supported on Docker Desktop for macOS. This mode allows Docker containers to share the host's network stack, which is essential for certain applications. However, Docker Desktop for macOS doesn't support this mode, leading to the access issue I faced.

network_mode: "host" probably not working as expected · Issue #1031 · docker/for-mac

The solution was to use network_mode=bridge (the default if not specified) and set up port mapping (8123:8123). This configuration allows the container to map ports between the host and container, enabling network communication. With these adjustments, I successfully accessed the Home Assistant WebUI on my macOS.

Networking overview

version: '3.8'

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=YOUR_TIME_ZONE
    restart: unless-stopped
    # network_mode=bridge
    ports:
      - "8123:8123"

Second Issue: Home Assistant’s Default Configuration is Confusing

I planned to place the Home Assistant service behind my Nginx reverse proxy to manage incoming requests and enhance security. However, I quickly encountered another hurdle. Home Assistant’s default configuration did not natively support reverse proxies without additional setup. Specifically, I needed to configure the HTTP integration to work with reverse proxies.

# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

## commented out since missed if custom configuration.yaml is set.
automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

## how to validate
# ref: https://www.home-assistant.io/common-tasks/container/#configuration-check
## wowbro custom change
# https://www.home-assistant.io/integrations/http/
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.0.1
    - 10.0.0.2

This required adding specific HTTP integration settings to the configuration.yaml file. Initially, I attempted to simply insert the HTTP configuration into the default configuration.yaml, but this approach failed. I realized that when you provide a custom configuration.yaml, Home Assistant does not automatically generate all the default configuration files ( although they are just empty ), which are necessary for the system to function correctly.

• automations.yaml
• scripts.yaml
• scenes.yaml

To resolve this, I had two options: either comment out the configuration lines that load these additional YAML files or manually provide the default configuration files. This step was crucial to ensure that all necessary configurations were in place, allowing Home Assistant to operate correctly behind the reverse proxy.

# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

## commented out since missed if custom configuration.yaml is set.
# automation: !include automations.yaml
# script: !include scripts.yaml
# scene: !include scenes.yaml

## how to validate
# ref: https://www.home-assistant.io/common-tasks/container/#configuration-check
## wowbro custom change
# https://www.home-assistant.io/integrations/http/
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 10.0.0.1
    - 10.0.0.2

Third Issue: Reverse Proxy Must Handle WebSocket

The final issue revolved around WebSocket support. Home Assistant relies heavily on WebSocket for real-time communication between the frontend and backend. This means that any reverse proxy setup must be capable of handling WebSocket connections.

When configuring Nginx as a reverse proxy for Home Assistant, I had to ensure that it was set up to support WebSocket. This involved adding specific directives to the Nginx configuration to pass WebSocket requests correctly. Here’s an example of the necessary configuration:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://<home-assistant>:8123;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade"; directives are essential. They ensure that the WebSocket connection upgrade requests are properly handled by Nginx, allowing seamless communication between the client and the Home Assistant backend.

Conclusion

Setting up Home Assistant with Nginx as a reverse proxy was a learning experience. Despite the initial hurdles — accessing the WebUI, configuring the default settings, and enabling WebSocket support — I managed to get everything up and running. For anyone attempting a similar setup, understanding these issues and their solutions can save a significant amount of time and frustration. With the right configuration, Home Assistant can be a powerful tool for home automation, even when deployed behind a robust reverse proxy like Nginx.

NEXT

HomeAssistant: Local testing with Nginx Reverse Proxy — macOS