SYS ONLINESTATUSOPEN FOR WORK
LunaByte
Back to Blog

Stop Typing IP Addresses: Setting Up Friendly Domain Names for Home Assistant

8 min read
Home AssistantDockerLinuxNginxSmart HomeSelf-Hosting

Stop Typing IP Addresses: Setting Up Friendly Domain Names for Home Assistant

Are you tired of typing http://192.168.1.100:8123 every time you want to check if you left the lights on? Do you dream of simply typing homeassistant.local into your browser and magically connecting to your smart home dashboard? Good news - you can make that dream a reality with just a bit of Linux magic!

In this guide, I'll show you how to set up friendly .local domain names for your Home Assistant instance running in Docker. We'll create a system that automatically publishes these domain names on your local network and directs traffic to the right places.

What You'll Get

  • Friendly domain names like homeassistant.local that work on your local network
  • A simple command to add new domains whenever you need them
  • A clean, professional way to access your self-hosted services

Prerequisites

Before we begin, you'll need:

  • A Linux server with Docker installed
  • Home Assistant running in a Docker container
  • Basic familiarity with the command line
  • Root or sudo access

If you don't have Home Assistant running yet, the official Docker command to set it up is:

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=YOUR_TIME_ZONE \
  -v /path/to/your/config:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Step 1: Install Required Packages

Let's start by installing the tools we need:

sudo apt update
sudo apt install nginx avahi-utils

This installs:

  • Nginx: A web server that will act as our reverse proxy
  • Avahi-utils: The tools we'll use to publish our domain names

Step 2: Set Up the Automation System

We'll create a simple system that makes it easy to add and manage local domains:

First, create a directory to store our configuration:

sudo mkdir -p /etc/mdns-publish

Next, create a configuration file for hostname mappings:

sudo nano /etc/mdns-publish/hostnames.conf

Add your Home Assistant details (replace with your actual IP address):

# Format: hostname IP port
homeassistant.local 192.168.1.100 8123

Now, let's create an automation script that makes adding new domains a breeze:

sudo nano /usr/local/bin/add-local-domain

Paste in this script:

#!/bin/bash
# Usage: add-local-domain domain.local IP PORT [websocket]

if [ "$#" -lt 3 ]; then
  echo "Usage: $0 domain.local IP PORT [websocket]"
  exit 1
fi

DOMAIN=$1
IP=$2
PORT=$3
WEBSOCKET=${4:-no}

# Add to hostnames file
echo "$DOMAIN $IP $PORT" >> /etc/mdns-publish/hostnames.conf

# Rebuild mDNS service file
SERVICE_FILE="/etc/systemd/system/mdns-hostname-publisher.service"
echo "[Unit]
Description=Publish mDNS hostname aliases with Avahi
After=network.target avahi-daemon.service

[Service]
Type=simple
ExecStart=/bin/sh -c \"" > $SERVICE_FILE

# Add each hostname from the config file
while read -r line; do
  # Skip comments and empty lines
  [[ "$line" =~ ^#.*$ || -z "$line" ]] && continue

  DOMAIN=$(echo $line | awk '{print $1}')
  IP=$(echo $line | awk '{print $2}')

  echo "/usr/bin/avahi-publish -a -R $DOMAIN $IP & " >> $SERVICE_FILE
done < /etc/mdns-publish/hostnames.conf

echo "wait\"
Restart=on-failure

[Install]
WantedBy=multi-user.target" >> $SERVICE_FILE

# Create nginx config
NGINX_CONFIG="/etc/nginx/sites-available/$DOMAIN"

echo "server {
    listen 80;
    listen [::]:80;

    server_name $DOMAIN;

    location / {
        proxy_pass http://$IP:$PORT;

        # Standard proxy headers
        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;" > $NGINX_CONFIG

# Add WebSocket support if requested
if [ "$WEBSOCKET" = "yes" ]; then
  echo "
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection \"upgrade\";

        # Disable buffering
        proxy_buffering off;" >> $NGINX_CONFIG
fi

echo "    }
}" >> $NGINX_CONFIG

# Enable the site
ln -sf $NGINX_CONFIG /etc/nginx/sites-enabled/

# Reload services
systemctl daemon-reload
systemctl restart mdns-hostname-publisher.service
nginx -t && systemctl reload nginx

echo "Domain $DOMAIN added and configured!"

Make the script executable:

sudo chmod +x /usr/local/bin/add-local-domain

Step 3: Configure Home Assistant

We need to tell Home Assistant to accept connections through our proxy. Edit your Home Assistant configuration file:

# Replace with your actual Home Assistant config path
sudo nano /path/to/your/homeassistant/config/configuration.yaml

Add these lines:

# HTTP configuration for proxy support
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1
    - 192.168.1.100  # Your server's IP address

Restart Home Assistant:

docker restart homeassistant

Step 4: Set Up Your First Domain

Let's set up our Home Assistant domain:

sudo add-local-domain homeassistant.local 192.168.1.100 8123 yes

This will:

  1. Add homeassistant.local to your hostnames file
  2. Create a systemd service to publish the hostname
  3. Set up nginx to proxy requests to Home Assistant
  4. Enable WebSocket support (needed for Home Assistant)

Step 5: Start Everything Up

Let's make sure all services are running:

sudo systemctl daemon-reload
sudo systemctl enable mdns-hostname-publisher.service
sudo systemctl start mdns-hostname-publisher.service
sudo systemctl restart nginx

Testing Your Setup

Now for the moment of truth! Open a browser and navigate to:

http://homeassistant.local

If everything worked correctly, you should see your Home Assistant dashboard!

Adding More Services

Want to add more services? It's as simple as:

sudo add-local-domain jellyfin.local 192.168.1.100 8096 yes
sudo add-local-domain nextcloud.local 192.168.1.100 8080 no

The last parameter (yes or no) indicates whether the service needs WebSocket support.

Troubleshooting

If things aren't working as expected, try these fixes:

Can't resolve the hostname

Try pinging the domain:

ping -c 2 homeassistant.local

If it doesn't resolve, check if the mDNS publisher is running:

systemctl status mdns-hostname-publisher.service

Getting 400 Bad Request errors

This usually means Home Assistant doesn't trust the proxy. Double-check your configuration.yaml to make sure the trusted_proxies section includes your server's IP address.

Browser says "This site can't be reached"

Make sure nginx is running and the configuration is valid:

systemctl status nginx
sudo nginx -t

Conclusion

Congratulations! You now have a clean, professional way to access your Home Assistant installation using a friendly domain name. No more remembering IP addresses and port numbers!

This setup not only makes your services easier to access but also lays the groundwork for more advanced configurations in the future.

What other services will you add to your local domain setup? I'd love to hear about your self-hosting adventures - reach out on socials or shoot me an email!

Back to all posts