Koenkk · Nerivec · Mar 15, 2025 · Mar 17, 2025 · Mar 17, 2025 · Mar 17, 2025
diff --git a/docs/guide/getting-started/README.md b/docs/guide/getting-started/README.md
@@ -24,126 +24,48 @@ See [Improve network range and stability](../../advanced/zigbee/02_improve_netwo
 
 ## Installation
 
-You can run Zigbee2MQTT in different ways, see [Installation](../installation/). In this example
-[Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) is used to
-set up and run Zigbee2MQTT.
+The next step is to install Zigbee2MQTT, follow [installation instructions](../installation/) for your platform. Once Zigbee2MQTT is started, you can continue with the onboarding procedure below.
 
-### 1.) Find the Zigbee-Adapter
+## Onboarding
 
-#### 1.1) USB Zigbee adapter
+You can run Zigbee2MQTT in different ways, see [Installation](../installation/).
 
-After you plug the adapter in see the `dmesg` output to find the device location:
+Zigbee2MQTT offers an onboarding process on first run (when no `configuration.yaml` exists).
 
-```bash
-$ sudo dmesg
+The onboarding page, by default, is reachable at the same URL as the frontend (`http://localhost:8080`). _Note: This URL may be different for specific setups (like Home Assistant)._
 
-...
-usbcore: registered new interface driver ch341
-usbserial: USB Serial support registered for ch341-uart
-ch341 3-1:1.0: ch341-uart converter detected
-usb 3-1: ch341-uart converter now attached to ttyUSB0
-```
-
-As we can see the adapter was identified and mounted on `ttyUSB0`.
-
-```bash
-$ ls -l /dev/ttyUSB0
-crw-rw---- 1 root dialout 188, May 16 19:15 /dev/ttyUSB0
-```
-
-Here we can see that the adapter is owned by `root` and accessible from all users in the `dialout` group.
-
-#### 1.2) Network Zigbee adapter
-
-Zigbee2MQTT supports mDNS autodiscovery feature for network Zigbee adapters. If your network Zigbee adapter supports mDNS, you do not need to know the IP address of your network Zigbee adapter, Zigbee2MQTT will detect it and configure. Otherwise, you need to know the network Zigbee adapter's IP address:
-
-- Connect your adapter to your LAN network either over Ethernet or Wi-Fi, depending on your adapter.
-- Go to your router/switch setting and find the list of connected device.
-- Find the IP address and of your Ethernet Zigbee adapter.
-- You also need to know the communication port of your Ethernet Zigbee-Adapter. In most cases (TubeZB, SLZB-06) the default port is `6638`. You can check the port at your Adapter's user manual.
-
-### 2.) Setup and start Zigbee2MQTT
-
-#### 2.1) Configure Docker
-
-It's assumed, that you have a recent version of Docker and Docker Compose installed.
-
-First, we create a folder where we want the project to reside `mkdir folder-name`. In the folder, we create we save the `docker-compose.yml` file which defines how Docker would run our containers. The following file consists of two services, one for the MQTT-Server and one for Zigbee2MQTT itself. Be sure to adjust the file to your needs and match the devices-mount in the case your adapter was not mounted on `/dev/ttyUSB0` or in case you use a network adapter.
-
-```yaml
-version: '3.8'
-services:
-    mqtt:
-        image: eclipse-mosquitto:2.0
-        restart: unless-stopped
-        volumes:
-            - './mosquitto-data:/mosquitto'
-        ports:
-            - '1883:1883'
-            - '9001:9001'
-        command: 'mosquitto -c /mosquitto-no-auth.conf'
-
-    zigbee2mqtt:
-        container_name: zigbee2mqtt
-        restart: unless-stopped
-        image: koenkk/zigbee2mqtt
-        volumes:
-            - ./zigbee2mqtt-data:/app/data
-            - /run/udev:/run/udev:ro
-        ports:
-            - 8080:8080
-        environment:
-            - TZ=Europe/Berlin
-        devices:
-            - /dev/ttyUSB0:/dev/ttyUSB0
-```
+If you successfully configure everything during onboarding, you can skip the following steps in the guide below: `1.1`, `1.2`, and `2.2`.
+If the `adapter type` is unknown by the discovery process, you can find a list of the most common adapters in the corresponding pages: [zstack](../adapters/zstack.md), [ember](../adapters/emberznet.md), [deconz](../adapters/deconz.md), [zigate](../adapters/zigate.md), [zboss](../adapters/zboss.md).
 
-#### 2.2) Configure Zigbee2MQTT
-
-In the next step we'll create a simple [Zigbee2MQTT config file](../configuration/) in `zigbee2mqtt-data/configuration.yaml`.
-
-NOTE: Docker Compose makes the MQTT-Server available using "mqtt" hostname.
-
-<Configurator mqtt="mqtt://mqtt" serial="/dev/ttyUSB0" portType="Serial" adapter="zstack" />
-
-For network adapters, `serial` > `port` settings should look like this:
-
-```yaml
-serial:
-    port: tcp://192.168.1.12:6638
-```
+:::tip TIP
+The adapter discovery process will try to find serial and mDNS-discoverable devices.
+Refreshing the page will re-execute the discovery process.
 
-Where `192.168.1.112` is the IP address of your network Zigbee adapter, and `6638` is the port.
-
-In case you adapter supports mDNS, you can omit the IP address and use a configuration like:
-
-```yaml
-serial:
-    port: mdns://slzb-06
-```
-
-Where `slzb-06` is the mDNS name of your network Zigbee adapter.
-
-#### 2.3) Start Zigbee2MQTT
+_Note: This may not be available on all setups. If not, you will have to enter the adapter path and type manually._
+:::
 
-We should now have two files in our directory and can start the stack:
+If Zigbee2MQTT fails validation after submitting the configuration, the page will show the error details.
 
-```bash
-$ find
-./docker-compose.yml
-./zigbee2mqtt-data/configuration.yaml
+If Zigbee2MQTT fails to start after submitting the initial configuration (due to something like a wrong adapter path), the onboarding will be executed again on the following start.
 
-# First start
-$ docker compose up -d
+:::tip TIP
+Onboarding failure pages will hold the `node` process from exiting until the page's `Close` button is triggered or the process is manually exited.
+:::
 
-# Check the logs
-$ docker compose logs -f
-```
+:::tip TIP
+You can also force the onboarding to run later (if configuration needs changing) with the environment variable `Z2M_ONBOARD_FORCE_RUN=1`.
+Depending on your setup, this may be offered in form of a toggle (Home Assistant add-on for example), or you may have to set it manually for the `node` process.
+:::
 
-After some short time you should see some log messages that Mosquitto and Zigbee2MQTT is running now.
-You can open the frontend using [http://localhost:8080](http://localhost:8080) (or the hostname of your remote server).
+:::details Environment variables available to customize the onboarding process
+The following environment variables are available, if your setup requires customizing the onboarding server:
 
-We can now go on and pair our first device.
+- `Z2M_ONBOARD_NO_SERVER=1` => disable onboarding server completely (_supersedes all below_)
+- `Z2M_ONBOARD_URL=http://localhost:8080` => set the URL where the onboarding page can be reached
+- `Z2M_ONBOARD_NO_FAILURE_PAGE=1` => disable failure pages (_failure is logged, and the process exits immediately_)
+- `Z2M_ONBOARD_FORCE_RUN=1` => see above TIP
+- `Z2M_ONBOARD_NO_REDIRECT=1` => if frontend is enabled, prevent the onboarding validation page from trying to redirect to frontend (_useful for setups where frontend has an unusual URL_)
+  :::
 
 ## Connect a device
 
@@ -156,8 +78,3 @@ Once you see something similar to below in the log your device is paired and you
 ```
 Zigbee2MQTT:info  2019-11-09T12:19:56: Successfully interviewed '0x00158d0001dc126a', device has successfully been paired
 ```
-
-::: warning ATTENTION
-It's important that `permit_join` is set to `false` in your `configuration.yaml` after initial setup is
-done to keep your Zigbee network safe and to avoid accidental joining of other Zigbee devices.
-:::
diff --git a/docs/guide/installation/01_linux.md b/docs/guide/installation/01_linux.md
@@ -68,6 +68,10 @@ pnpm --version
 
 ## Configuring
 
+:::tip TIP
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding).
+:::
+
 Before we can start Zigbee2MQTT we need to copy and edit the `configuration.yaml` file. This file contains the configuration which will be used by Zigbee2MQTT.
 
 Copy and open the configuration file:

diff --git a/docs/guide/installation/02_docker.md b/docs/guide/installation/02_docker.md
@@ -15,10 +15,20 @@ Start by figuring out the location of your adapter as explained [here](../config
 
 ## Creating the initial configuration
 
-Navigate to the directory where you will store the Zigbee2MQTT data and execute the following command:
+Navigate to the directory where you will store the Zigbee2MQTT data and execute the following command to create the folder:
 
 ```bash
-mkdir data && wget https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/data/configuration.example.yaml -O data/configuration.yaml
+mkdir data
+```
+
+:::tip TIP
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding). It will allow you to configure this on container start via a simple frontend page.
+:::
+
+You can grab the default `configuration.yaml` with the following command:
+
+```bash
+wget https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/data/configuration.example.yaml -O data/configuration.yaml
 ```
 
 Now configure the MQTT server and adapter location as explained [here](./01_linux.md#configuring).

diff --git a/docs/guide/installation/05_windows.md b/docs/guide/installation/05_windows.md
@@ -45,6 +45,10 @@ In order to be able to communicate with your USB device over a virtual COM port,
 
 ## Configuring
 
+:::tip TIP
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding).
+:::
+
 1. Copy `data\configuration.example.yaml` to `data\configuration.yaml`
 1. Open `data\configuration.yaml` in a text editor
 1. Change the MQTT configuration to match your setup, see the [documentation](../configuration/mqtt.md) for more info.

diff --git a/docs/guide/installation/06_freebsd_jail.md b/docs/guide/installation/06_freebsd_jail.md
@@ -51,6 +51,10 @@ pnpm run build
 
 ## Configuring
 
+:::tip TIP
+As an alternative of this, you can also use [Onboarding](../getting-started/README.md#onboarding).
+:::
+
 Configuration is the same as on [Linux](01_linux.md#configuring).
 
 Note that the `configuration.yaml` is at a different location: