// install

Installation guide

Choose the method that fits your stack. We recommend Docker Compose for persistent setups.

Docker Compose Recommended

Best for long-term usage with persistent data.

services:
  d2ha:
    image: ghcr.io/arborae/docker2homeassistant:latest
    container_name: d2ha
    restart: unless-stopped
    ports:
      - "12021:12021"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./data:/app/data
    environment:
      D2HA_SECRET_KEY: "change-this-secret"

Docker Run Quick test

Good for testing quickly without a compose file.

docker run -d \
  --name d2ha \
  -p 12021:12021 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v $(pwd)/data:/app/data \
  -e D2HA_SECRET_KEY="change-me" \
  ghcr.io/arborae/docker2homeassistant:latest

Configuration tips

Use MQTT_BROKER, MQTT_USERNAME and related environment variables to pre-configure the MQTT connection.

Prefer living on the edge? The :nightly image tag ships the latest features — potentially unstable.

First login

Open http://localhost:12021 and sign in with:

Username: admin
Password: admin

You will be prompted to change these immediately.

Stuck on something?

Open an issue on GitHub — clear reports get fixed fast.

Get help