## Prerequisites

Before starting, ensure you have a compatible Zigbee coordinator and a computer running a clean **Debian Bookworm** (Debian 12).

## 1\. Install Dependencies

First, update your package list and install the necessary dependencies for Zigbee2Mqtt, including `git` and `build-essential`. These are required to clone the repository and compile some of the components.

```bash
sudo apt update
sudo apt install git build-essential
```

-----

## 2\. Install Node.js

Zigbee2Mqtt is built on Node.js. Although Debian 12 comes with a version of Node.js, it is often not the latest. For better compatibility, it's recommended to install the official Node.js binaries. You can find the instructions for this on the [Node.js website](https://www.google.com/search?q=https://nodejs.org/en/download/package-manager%23debian-and-ubuntu-based-linux-distributions).

```bash
# This is an example, check the Node.js website for the latest instructions
sudo apt install curl
curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install nodejs
```

-----

## 3\. Create a Swap File (Optional but Recommended)

If your system has limited RAM (e.g., 512 MB or less), creating a swap file is highly recommended. A swap file uses a portion of your hard drive as a temporary memory overflow, which can prevent the "out of memory" errors that can occur during the installation and operation of Zigbee2MQTT.

1.  **Create a swap file.** The following command creates a 2 GB swap file in your root directory. You can change the size by adjusting the `-l` flag.
    ```bash
    sudo fallocate -l 2G /swapfile
    ```
2.  **Set the correct permissions.** Only the root user should be able to read and write to the swap file.
    ```bash
    sudo chmod 600 /swapfile
    ```
3.  **Set up the swap space.** This command formats the file as a swap file.
    ```bash
    sudo mkswap /swapfile
    ```
4.  **Enable the swap file.** This command activates the swap file for the current session.
    ```bash
    sudo swapon /swapfile
    ```
5.  **Make the swap file permanent.** To ensure the swap file is enabled automatically after a reboot, add the following line to the end of your `/etc/fstab` file.
    ```bash
    /swapfile none swap sw 0 0
    ```

-----

## 4\. Install zigbee2mqtt

Now you can install Zigbee2Mqtt. The best way to do this is to clone the official Git repository into a directory you've created for the application.

```bash
sudo mkdir /opt/zigbee2mqtt
sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
```

Navigate to the newly created directory and install the Node.js dependencies. 

```bash
cd /opt/zigbee2mqtt
npm install
```

If you encounter a `FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory`, run the command with increased heap space.

```bash
node --max-old-space-size=2048 /usr/bin/npm install
```

-----

## 5\. Configure zigbee2mqtt

The next step is to configure Zigbee2Mqtt. The primary configuration file is `configuration.yaml` located in the `/opt/zigbee2mqtt/data` directory. Use a text editor like `nano` to edit the file.

```bash
sudo nano /opt/zigbee2mqtt/data/configuration.yaml
```

At a minimum, you'll need to specify the **serial port** of your Zigbee coordinator. The correct path for your device will be something like `/dev/ttyACM0` or `/dev/ttyUSB0`. You can use the `dmesg` command after plugging in your device to see what port it's assigned to.

```yaml
# In /opt/zigbee2mqtt/data/configuration.yaml
homeassistant: false
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost
serial:
  port: /dev/ttyACM0
```

> 💡 **Note:** If you want to integrate with **Home Assistant** or another MQTT broker, you will need to change the `homeassistant` and `mqtt` settings accordingly.

-----

## 6\. Create a Systemd Service

To ensure Zigbee2Mqtt starts automatically on boot and runs as a background service, it's best to create a **systemd service file**. This file will control the service's behavior.

Create a new file called `zigbee2mqtt.service` in the `/etc/systemd/system/` directory.

```bash
sudo nano /etc/systemd/system/zigbee2mqtt.service
```

Add the following content to the file:

```ini
[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
Restart=always
User=root

[Install]
WantedBy=multi-user.target
```

Reload the systemd daemon to recognize the new service and then enable and start it.

```bash
sudo systemctl daemon-reload
sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee2mqtt.service
```

-----

## 7\. Check the Status

You can check the status of the service at any time to ensure it is running correctly.

```bash
sudo systemctl status zigbee2mqtt.service
```

This command will show you the service's status, including whether it's active and any recent log entries. If you have any issues, the logs will be a good place to start troubleshooting.

-----

## 8\. How to Update Node.js and Zigbee2MQTT

The best way to update both Node.js and Zigbee2MQTT is to stop the service, perform the updates, and then restart the service. It's a good practice to back up your Zigbee2MQTT configuration files before updating.

### ⚙️ Update Node.js

Since you installed Node.js from the NodeSource repository, you can update it using the `apt` package manager. First, you'll need to run the NodeSource setup script for the latest LTS version, which will update the repository's configuration. Then you can update the package itself.

1.  **Stop the Zigbee2MQTT service:**
    ```bash
    sudo systemctl stop zigbee2mqtt.service
    ```
2.  **Run the NodeSource script to update the repository:**
    ```bash
    curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
    ```
    This command will reconfigure your system to point to the latest LTS version of Node.js.
3.  **Update and upgrade Node.js:**
    ```bash
    sudo apt update
    sudo apt upgrade nodejs -y
    ```
    This will install the newest version of Node.js available from the NodeSource repository.

-----

### 🔄 Update Zigbee2MQTT

Updating Zigbee2MQTT is straightforward. You just need to pull the latest changes from the Git repository and then install any new dependencies.

1.  **Navigate to the Zigbee2MQTT directory:**
    ```bash
    cd /opt/zigbee2mqtt
    ```
2.  **Pull the latest code from the Git repository:**
    ```bash
    sudo git pull
    ```
    This command downloads and applies the most recent changes from the official Zigbee2MQTT repository.
3.  **Install new Node.js dependencies:**
    ```bash
    npm install
    # If you get an 'out of memory' error, use this command instead:
    node --max-old-space-size=2048 /usr/bin/npm install
    ```
    This ensures that any new or updated dependencies required by the latest version of Zigbee2MQTT are installed correctly.
4.  **Restart the Zigbee2MQTT service:**
    ```bash
    sudo systemctl start zigbee2mqtt.service
    ```
5.  **Check the service status to confirm it's running:**
    ```bash
    sudo systemctl status zigbee2mqtt.service
    ```
    This will show you the status and recent logs, confirming that the update was successful and the service is active.

-----

### 9\. Migrate a Running Zigbee2MQTT Instance to New Hardware

The migration process is simple and primarily involves backing up and restoring your data files. The **data** directory contains all the essential information about your Zigbee network, including device pairings and configurations, which are crucial for a seamless transition.

#### On the Old System:

1.  **Stop the Zigbee2MQTT service.** This ensures that the configuration and database files are not being written to while you're backing them up, preventing data corruption.

    ```bash
    sudo systemctl stop zigbee2mqtt.service
    ```

2.  **Navigate to the Zigbee2MQTT data directory.** This is where all your important network files are stored. By default, this is `/opt/zigbee2mqtt/data`.

    ```bash
    cd /opt/zigbee2mqtt/data
    ```

3.  **Create a backup of your data directory.** You can compress the entire directory into a single file to make it easier to transfer.

    ```bash
    tar -czvf zigbee2mqtt_backup.tar.gz .
    ```

    This command creates a compressed archive named `zigbee2mqtt_backup.tar.gz` that contains all the files in the current directory.

4.  **Copy the backup file to your new hardware.** You can use a tool like `scp` (secure copy) or a USB drive to transfer the file. Replace `<user>` and `<new_server_ip>` with your new system's login details.

    ```bash
    scp zigbee2mqtt_backup.tar.gz <user>@<new_server_ip>:/home/<user>/
    ```

#### On the New System:

1.  **Follow steps 1 through 3** from the initial installation guide on the new hardware to install the dependencies, Node.js, and a fresh Zigbee2MQTT instance. **Do not** start the service yet.
2.  **Navigate to the new Zigbee2MQTT data directory:**
    ```bash
    cd /opt/zigbee2mqtt/data
    ```
3.  **Extract the backup files.** Use the `tar` command to decompress the archive you copied over.
    ```bash
    sudo tar -xzvf /path/to/zigbee2mqtt_backup.tar.gz
    ```
    This will overwrite the default `configuration.yaml` and other files with your old ones.
4.  **Edit the configuration file.** You'll need to update the `serial.port` in your `configuration.yaml` to match the new hardware's Zigbee coordinator port.
    ```bash
    sudo nano /opt/zigbee2mqtt/data/configuration.yaml
    ```
    Ensure the `port` value corresponds to the new location of your Zigbee dongle (e.g., `/dev/ttyACM0`).
5.  **Start the Zigbee2MQTT service.**
    ```bash
    sudo systemctl start zigbee2mqtt.service
    ```
    Your Zigbee2MQTT instance should now start up on the new hardware with all your devices, groups, and settings intact. The network should automatically re-establish itself. You can verify this by checking the service status and the Zigbee2MQTT frontend.