Skip to main content

Installation

This setup assumes, that you have a USB zigbee adapter, that is supported by Zigbee2Mqtt. You can find a list of supported adapters here.

For this guide we will use the ITead Sonoff Zigbee 3.0 USB Dongle Plus V2 model "ZBDongle-E". Make sure to flash it with the coordinator firmware, by following the instructions linked on the Zigbee2Mqtt website.

Pre-Installation

  1. Find your Zigbee Adapter. If it is working correctly, it should be available under /dev/serial/by-id/<device>, e.g.: /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20221101103853-if00.

  2. Create config/zigbee2mqtt/configuration.yaml and add the following:

    config/zigbee2mqtt/configuration.yaml
    permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mqtt:1883
  user: mqtt
  password: <password>
  include_device_information: true
homeassistant: true
serial:
  adapter: ezsp
  port: >-
    <z2m_device>
frontend:
  host: 0.0.0.0
  port: 8090
advanced:
  network_key: GENERATE
  homeassistant_legacy_entity_attributes: false
  legacy_api: false
  legacy_availability_payload: false
device_options:
  legacy: false

    Make sure to replace <z2m-device> by the path /dev/serial/by-id/<device> of your adapter. Also replace the <password> by a password of your choice. You will need it later for the homeassistant setup.

  3. Create the docker-compose.yml file and add the following

    docker-compose.yml
    version: '3.8'
services:
  mqtt:
    image: eclipse-mosquitto:2.0
    container_name: mqtt
    restart: unless-stopped
    volumes:
      - "./data/mosquitto:/mosquitto"
    ports:
      - "1883:1883"
      - "9001:9001"
    command: "mosquitto -c /mosquitto-no-auth.conf"

  zigbee2mqtt:
    container_name: zigbee2mqtt
    restart: unless-stopped
    image: koenkk/zigbee2mqtt
    volumes:
      - ./data/zigbee2mqtt:/app/data
      - ./config/zigbee2mqtt/configuration.yaml:/app/data/configuration.yaml
      - /run/udev:/run/udev:ro
    ports:
      - 8090:8080
    environment:
      - TZ=${TZ}
    devices:
      - ${Z2M_DEVICE}:${Z2M_DEVICE}
    labels:
      traefik.enable: true
      traefik.http.routers.z2m.entrypoints: websecure
      traefik.http.routers.z2m.middlewares: secured@file
      traefik.http.routers.z2m.rule: Host(`z2m.${SITE}`)
      traefik.http.services.z2m.loadbalancer.server.port: 8090
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - ./config/homeassistant:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    environment:
      PUID: ${PUID}
      GUID: ${PGID}
    labels:
      traefik.enable: true
      traefik.http.routers.homeassistant.entrypoints: websecure
      traefik.http.routers.homeassistant.rule: Host(`ha.${SITE}`) && !Path(`/api/prometheus`)
      traefik.http.services.homeassistant.loadbalancer.server.port: 8123

    Make sure to add Z2M_DEVICE=/dev/serial/by-id/<device> in your .env.

  4. Start the applications by running docker compose up -d

Back to top