Skip to content

Home

Jump to bottom
Nerivec edited this page Aug 12, 2025 · 27 revisions

Getting the latest updates

Use dev branch of Zigbee2MQTT: https://www.zigbee2mqtt.io/advanced/more/switch-to-dev-branch.html

Using your current Zigbee2MQTT version

Caution

Some updates will require a minimum version (commit) of Zigbee2MQTT to work properly. This is usually the case when a new feature is introduced and changes are needed in the frontend. See the Zigbee2MQTT dev branch changelog.

Tip

You can install a specific WindFront version using the format pnpm i [email protected], example: pnpm i [email protected]

Baremetal

Stop Zigbee2MQTT.

Inside your Zigbee2MQTT installation folder:

pnpm update zigbee2mqtt-windfront --no-optional

Start Zigbee2MQTT again.

Container

Example with Docker:

docker exec -it CONTAINER_ID sh
apk add npm
npm install -g [email protected]
/usr/local/bin/pnpm update zigbee2mqtt-windfront --no-optional
exit
docker restart CONTAINER_ID

Note: the pnpm version should be the same as used by Zigbee2MQTT:

Standalone serving (with multi-Zigbee2MQTT support)

You can run WindFront in a separate instance (independently of Zigbee2MQTT). This allows you to control the serving in more details and you can also use the same interface for multiple Zigbee2MQTT instances (switch available in the nav bar).

Important

Frontend needs to be enabled in the targeted Zigbee2MQTT instances.

Caution

Some updates will require a minimum version (commit) of Zigbee2MQTT to work properly. This is usually the case when a new feature is introduced and changes are needed in the frontend. See the Zigbee2MQTT dev branch changelog.

Tip

You can install a specific WindFront version using the release tags. For containers: https://github.com/Nerivec/zigbee2mqtt-windfront/pkgs/container/zigbee2mqtt-windfront/versions?filters%5Bversion_type%5D=tagged and for baremetal: https://github.com/Nerivec/zigbee2mqtt-windfront/tags

Docker

https://github.com/Nerivec/zigbee2mqtt-windfront/pkgs/container/zigbee2mqtt-windfront

The container is based on nginx:alpine-slim.

Configure environment variables

Make sure to configure docker-compose.yml to fit your needs (or using whatever system you use to start the Docker container).

  • Z2M_API_URLS allows to specify the addresses of the Zigbee2MQTT instances that will be available to pick from (comma-separated values, no space, first is default). Example: Z2M_API_URLS=one.local:8080/api,two.local:8080/api
  • Z2M_API_NAMES will label the corresponding URLs (if not supplied, labels will be URLs)
  • USE_PROXY=true if you need tunneling support
docker compose up -d zigbee2mqtt-windfront

WindFront should now be accessible at whatever location you configured (default: localhost:80).

Updating

docker compose pull zigbee2mqtt-windfront
docker compose up -d zigbee2mqtt-windfront

Home Assistant

An add-on is available: https://github.com/Nerivec/ha-zigbee2mqtt-windfront

Tip

If wanting to include a Zigbee2MQTT add-on instance from the same Home Assistant machine, be sure to get the correct ingress URL used by Home Assistant. This will depend on your setup, you will have to find the IP, port and ingress path accordingly.

Baremetal

Environment variables are the same as the Docker setup, except with VITE_ prefix: VITE_Z2M_API_URLS, VITE_Z2M_API_NAMES.

git clone --depth 1 https://github.com/Nerivec/zigbee2mqtt-windfront/
npm ci
# example: VITE_Z2M_API_URLS=localhost:5173/api,localhost:8080/api VITE_Z2M_API_NAMES=one,two npm run build
<ENVS> npm run build

Tip

You can pass the argument -b v0.0.0 to git clone to get a specific version (see: https://github.com/Nerivec/zigbee2mqtt-windfront/tags)

The content of the dist folder that will be created can then be served by your favorite software (nginx, etc.).

Updating

git pull
npm ci
<ENVS> npm run build

Clone this wiki locally