Skip to content

Run Home Assistant as a container with custom.yml

How-toDeployrr v6.0+CurrentDocker ComposeApp networkingTraefik

Home Assistant is not in the Deployrr v6 apps menu. Install it the way Home Assistant’s own guide recommends, for example Home Assistant OS in a VM or on another machine. The container install has no apps (add-ons) and no Supervisor. If you still want the container, add it yourself with custom.yml.

  1. Go to your Docker folder and open custom.yml.

    Terminal window
    cdd
    nano compose/$HOSTNAME/custom.yml
  2. Remove the # from # services: if it is still there, then add this service under it:

    services:
    homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    restart: unless-stopped
    stop_grace_period: 60s
    environment:
    - TZ=$TZ
    volumes:
    - $DOCKERDIR/appdata/homeassistant:/config
    - /etc/localtime:/etc/localtime:ro
    - /run/dbus:/run/dbus:ro

    $DOCKERDIR and $TZ are filled in from the .env file in your Docker folder. Don’t replace them. /run/dbus is only needed for Bluetooth. stop_grace_period gives Home Assistant time to shut down cleanly.

    Keep the indentation. If you already have other services in the file, add only the homeassistant: block under services:.

  3. Save the file.

  4. Start Home Assistant.

    Terminal window
    dcup homeassistant
  5. Follow the logs until the startup messages stop.

    Terminal window
    dclogs homeassistant

    Press Ctrl+C to stop following.

  6. Open http://SERVER_IP:8123 in your browser. Replace SERVER_IP with your server’s local IP address. Create the owner account.

network_mode: host lets Home Assistant find devices on your network and use mDNS and HomeKit. With it, the container shares the server’s network, so you must not add ports: or Docker networks:. Home Assistant listens on port 8123 of the server itself.

The cost is that other containers can’t reach it by name. Use the server’s IP address instead.

If UFW or firewalld runs on the server, port 8123 must be allowed from your home network and from Traefik. With host networking, the firewall applies to Home Assistant like to any program on the server. See Firewall rules below.

Add a Zigbee or Z-Wave USB stick (optional)

Section titled “Add a Zigbee or Z-Wave USB stick (optional)”
  1. Plug the stick into the server.

  2. List the stable device names.

    Terminal window
    ls -l /dev/serial/by-id/
  3. Add a devices: list to the service. Replace the path with the one from step 2.

    devices:
    - /dev/serial/by-id/YOUR_STICK_NAME:/dev/serial/by-id/YOUR_STICK_NAME
  4. Run dcup homeassistant again.

Use the by-id path, not /dev/ttyUSB0. The ttyUSB0 number can change after a reboot.

If Deployrr runs in a Proxmox LXC, the stick must reach the LXC first, or the path won’t exist. See Pass a USB stick into the container.

Traefikify needs a Plus or Pro license, with Socket Proxy and Traefik Production set up and Traefik running.

Follow Home Assistant behind Traefik. Two parts are different for the container:

  • In Traefikify, enter your server’s local IP address as the host IP, http as the protocol and 8123 as the port. Traefik can’t use the container name, because the container has no Docker network. To see the same idea done by hand for an app that is not in Docker’s network, watch Traefik guide: external HTTP apps behind Traefik at 9:03 (manual Docker Compose setup; Deployrr does this for you).
  • When you trust the proxy in Home Assistant, use the address Home Assistant sees. Open the logs with dclogs homeassistant and find the line A request from a reverse proxy was received from. Trust the address after from. In a standard Deployrr setup Traefik has the fixed address 192.168.90.254 on its proxy network, so that is the address you will often see. If you see another address, trust that one, and check the log again if the error comes back after Traefik is recreated.

In Home Assistant 2026.8 and later, set this in Settings > System > Network, in the HTTP server section: turn on Trust X-Forwarded-For and add the address or network under Trusted proxies. Saving restarts Home Assistant. Confirm the new settings when asked, or Home Assistant goes back to the old ones after 5 minutes.

Older versions use an http: block in appdata/homeassistant/configuration.yaml in the Docker folder. Edit it with sudo, then run dcrestart homeassistant:

http:
use_x_forwarded_for: true
trusted_proxies:
- 192.168.90.254

Replace 192.168.90.254 with the address from the log if it is different. When you update to 2026.8 or later, Home Assistant moves this block into the UI by itself and then ignores it.

If UFW or firewalld is on, allow port 8123 from your home network and from Traefik. Deployrr’s own firewall rule only allows the Socket Proxy network, 192.168.91.0/24. It adds no rule for Traefik’s 192.168.90.0/24 network. With UFW:

Terminal window
sudo ufw allow from 192.168.1.0/24 to any port 8123 proto tcp
sudo ufw allow from 192.168.90.254 to any port 8123 proto tcp

With firewalld:

Terminal window
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="8123" protocol="tcp" accept'
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.90.254" port port="8123" protocol="tcp" accept'
sudo firewall-cmd --reload

Replace 192.168.1.0/24 with your home network. Use the address from the Home Assistant log in place of 192.168.90.254 if it is different. If apps on a VPS lose internet or show certificate errors with UFW on, see Fix the UFW firewall on a VPS.

  1. Back up first, so you can go back if an update causes problems (see below).

  2. Pull the new image.

    Terminal window
    dcpull homeassistant
  3. Recreate the container.

    Terminal window
    dcup homeassistant

Stack Manager doesn’t list custom.yml services. Up includes them, but Update Stack doesn’t pull their images, so use dcpull. For background on pulling and recreating a Compose service, read UDMS part 13: updating services (manual setup; it uses other file paths).

The config folder is appdata/homeassistant inside your Docker folder. Tools > Backups > Backup (Pro license) saves the whole Docker folder, so it includes Home Assistant. It stops all running containers while it works and then asks whether to restart the stack. See Back up and restore your Docker folder. Home Assistant also has its own backup feature for its data.

If you ran Home Assistant as a v5 app, v5 kept its data in appdata/home-assistant (with a hyphen). v5 installed the Core version, so your settings are in that folder.

  1. Follow Move from v5 to v6, where you rename your v5 folder to docker-v5 and set up v6. Then turn on custom.yml.

  2. Add the service from this page, but do not start it yet.

  3. Copy the old folder to the new name. The -a option keeps owners and permissions.

    Terminal window
    sudo cp -a /home/USERNAME/docker-v5/appdata/home-assistant /home/USERNAME/docker/appdata/homeassistant

    Replace USERNAME with your Linux user name, and change the path if your Docker folder is elsewhere.

  4. Run dcup homeassistant.

  5. If you use Traefik, check the trusted proxies as shown above. v5 added an http: block for you, and its address may differ from what v6 needs.

  1. dps lists homeassistant with a status of Up.
  2. http://SERVER_IP:8123 shows the Home Assistant login or onboarding page.
  3. If you use Traefik, https://homeassistant.YOUR_DOMAIN shows the same page. Replace YOUR_DOMAIN with your domain.