Installation

D2HA runs on any amd64 or arm64 machine with Docker Engine 24 or newer. The recommended setup uses Docker Compose and includes a Docker socket proxy with secure defaults.

Docker Compose

1. Create a folder and download the example compose file:

   mkdir d2ha && cd d2ha
   curl -o compose.yaml https://raw.githubusercontent.com/Arborae/docker2homeassistant/main/compose.example.yaml

2. Read compose.yaml. Every option is optional and explained in the file: see Configuration for the full list.
3. Start it and read the setup code from the log:

   docker compose up -d
   docker logs d2ha

The example starts two containers:

• d2ha, published on 127.0.0.1:12021 only: Home Assistant on the same host, a reverse proxy or a tunnel can reach it, the rest of the network cannot;
• docker-proxy (linuxserver/socket-proxy), so D2HA never touches the Docker socket: it allows only the calls D2HA needs, and no exec, volumes or networks. The Security page explains every permission.

Docker run, for a quick look

docker run -d \
  --name d2ha \
  -p 127.0.0.1:12021:12021 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $(pwd)/data:/app/data \
  ghcr.io/arborae/docker2homeassistant:latest

First sign-in

1. Open D2HA. The example listens on 127.0.0.1 only, so:
   • in a browser on the server itself, open http://localhost:12021;
   • from another computer, open an SSH tunnel first (ssh -L 12021:localhost:12021 <user>@<server>), then http://localhost:12021 on that computer;
   • or go through your reverse proxy or tunnel, if you already have one.
2. Enter the setup code from docker logs d2ha: three groups of four characters, such as A1B2-C3D4-E5F6. It proves that you own the server.
3. Choose a username (3 to 32 letters, numbers, dots, dashes or underscores) and a password of at least 10 characters. A passphrase is easy to remember and hard to guess.
4. D2HA opens Settings. Turn on two-factor authentication, then connect Home Assistant.

Image tags

Images are published on ghcr.io/arborae/docker2homeassistant for amd64 and arm64.

Updating D2HA

D2HA cannot update itself, because it would stop halfway. In the folder of compose.yaml:

docker compose pull
docker compose up -d

This updates the socket proxy too, which D2HA never updates either. The account, the settings and the Home Assistant token live in the data folder and stay as they are.

Next steps

• Connect Home Assistant, then add the dashboard.
• Set up Telegram notifications.
• Keep it private: read Security.

Something wrong or missing on this page? Open an issue.