Matterbridge Docker configuration

---

Production configuration

Run Matterbridge with Docker and Docker Compose

The Matterbridge Docker images (multi-arch manifest list for linux/amd64 and linux/arm64) are published on Docker Hub. If you use them, please consider starring the project on Docker Hub.

The image (tag latest 87 MB) includes only Matterbridge, using the latest release published on npm. It is based on node:24-trixie-slim. Plugins are not included in the image: they will be reinstalled on first run.

The image (tag dev 99 MB) includes Matterbridge and all official plugins (the BTHome plugin is not included and requires additional setup) from the latest push on GitHub. It is based on node:24-trixie-slim. Since all official plugins are included, you can select and add a plugin without installing anything. Note: if you update to the latest dev from the frontend, you will override the GitHub version with the latest dev published on npm. The frontend shows if you are currently running the GitHub release or the latest or dev npm release.

The image (tag ubuntu 87 MB) includes only Matterbridge, using the latest release published on npm. This image is based on ubuntu:latest with Node.js 24 from NodeSource. Plugins are not included in the image: they will be reinstalled on first run. This image, on the first run, preinstalls bluetooth, build-essential, and python packages (useful for plugins that require native builds).

The image (tag alpine 58 MB) includes only Matterbridge, using the latest release published on npm. This image is based on node:24-alpine. Plugins are not included in the image: they will be reinstalled on first run.

The image (tag bun 69 MB) includes only Matterbridge, using the latest release published on npm. This image (for test and development only) is based on oven/bun:slim. Plugins are not included in the image: they will be reinstalled on first run.

The image (tag s6-rc 83 MB) includes only Matterbridge, using the latest release published on npm. This image is based on node:24-trixie-slim, supports arm64, amd64 and integrates the s6-rc overlay system. Plugins are not included in the image: they will be reinstalled on first run. It is only used for the Matterbridge Home Assistant Application.

The image (tag s6-rc-legacy 83 MB) includes only Matterbridge, using the latest release published on npm. This image is based on node:22-bullseye-slim, supports arm64, amd64 and arm/v7 and integrates the s6-rc overlay system. Plugins are not included in the image: they will be reinstalled on first run. It is only used for the legacy Matterbridge Home Assistant Application (Legacy).

Matterbridge chip-tool docker image

The image (tag chip-test 400MB) is based on ubuntu:latest with Node.js 24 LTS from NodeSource and includes the connectedhomeip repository with chip-tool, chip-cert and all components required for yaml and phyton tests. The matterbridge instance inside the container is already paired in the chip-tool fabric to execute yaml tests and in the python harness fabric to execute python tests. In the container, the chip environment and phyton environment are already active. Just open a shell inside the container with bash and run the tests. Matterbridge frontend is as usual on port 8283. No volumes or port mapping needed.

Matterbridge docker base images

The image (tag 24-ubuntu-slim 83 MB) is based on ubuntu:latest with Node.js 24 LTS from NodeSource. It is used to build the ubuntu image but can also be used to open a shell in ubuntu latest with node 24 (node doesn't publish node:24-ubuntu).

Docker health check

All images include a health check.

How health checks work in different scenarios:

• With Docker Compose: Docker monitors the health check and can restart the container (depending on your restart policy).
• With docker run: the health check still runs, but the container will not restart automatically when it becomes unhealthy.

You can manually check the health status:

docker exec -it matterbridge mb_health

Create the Matterbridge directories first

This creates the required directories in your home directory (if they don't already exist):

cd ~
mkdir -p ~/Matterbridge
mkdir -p ~/.matterbridge
mkdir -p ~/.mattercert
sudo chown -R $USER:$USER ~/Matterbridge ~/.matterbridge ~/.mattercert

You may need to adapt the paths to your setup.

Add your user to the docker group

If you don't want to use sudo with docker commands, run this command:

sudo groupadd docker
sudo usermod -aG docker $USER

After adding your user to the docker group, log out and log back in so your current session picks up the new group membership.

Run the container

The container must have full access to the host network (needed for mDNS and the Matter protocol).

Linux (bash):

sudo docker pull luligu/matterbridge:latest
sudo docker stop matterbridge 2>/dev/null
sudo docker rm matterbridge 2>/dev/null
sudo docker run --name matterbridge \
  -v ~/Matterbridge:/root/Matterbridge \
  -v ~/.matterbridge:/root/.matterbridge \
  -v ~/.mattercert:/root/.mattercert \
  --network host --restart always --stop-timeout 60 -d luligu/matterbridge:latest

You may need to adapt the paths to your setup.

Run the container with extra parameters (e.g. frontend on port 8585)

sudo docker pull luligu/matterbridge:latest
sudo docker stop matterbridge 2>/dev/null
sudo docker rm matterbridge 2>/dev/null
sudo docker run --name matterbridge \
  -v ~/Matterbridge:/root/Matterbridge \
  -v ~/.matterbridge:/root/.matterbridge \
  -v ~/.mattercert:/root/.mattercert \
  --network host --restart always  --stop-timeout 60 -d luligu/matterbridge:latest \
  matterbridge --docker --frontend 8585

If you override the command, always start it with matterbridge --docker.

If you change the frontend port (or enable https), overriding the default command of the images, docker will report the container unhealty unless you add the --no-healthcheck param.

How to run a double instance of matterbridge

In edge cases when you need a double instance of a matterbridge plugin (like for zigbee2mqtt when you have two mqtt brokers), you can run a double instance of matterbridge using the profiles.

cd ~
mkdir -p ~/matterbridge-one
mkdir -p ~/matterbridge-two
sudo chown -R $USER:$USER ~/matterbridge-one ~/matterbridge-two
sudo docker pull luligu/matterbridge:latest
sudo docker stop matterbridge-one 2>/dev/null
sudo docker rm matterbridge-one 2>/dev/null
sudo docker run --name matterbridge-one -v ~/matterbridge-one/Matterbridge:/root/Matterbridge -v ~/matterbridge-one/.matterbridge:/root/.matterbridge -v ~/matterbridge-one/.mattercert:/root/.mattercert --network host --restart always --stop-timeout 60 --no-healthcheck -d luligu/matterbridge:latest matterbridge --docker --frontend 8081 --port 5540 --profile BrokerOne
sudo docker stop matterbridge-two 2>/dev/null
sudo docker rm matterbridge-two 2>/dev/null
sudo docker run --name matterbridge-two -v ~/matterbridge-two/Matterbridge:/root/Matterbridge -v ~/matterbridge-two/.matterbridge:/root/.matterbridge -v ~/matterbridge-two/.mattercert:/root/.mattercert --network host --restart always --stop-timeout 60 --no-healthcheck -d luligu/matterbridge:latest matterbridge --docker --frontend 8082 --port 5560 --profile BrokerTwo

The first instance (profile BrokerOne) has the frontend on port 8081 and Matter port starting at 5540.

The second instance (profile BrokerTwo) has the frontend on port 8082 and Matter port starting at 5560.

Both instances have healthcheck disabled.

Run with Docker Compose

The docker-compose.yml file is available in the docker directory of this repository:

services:
  matterbridge:
    container_name: matterbridge
    image: luligu/matterbridge:latest # Matterbridge image with the tag latest
    network_mode: host # Ensures the Matter mDNS works
    restart: always # Ensures the container always restarts automatically
    stop_grace_period: 60s # Sets the grace period for stopping the container to 60 seconds
    volumes:
      - '${HOME}/Matterbridge:/root/Matterbridge' # Mounts the Matterbridge plugin directory
      - '${HOME}/.matterbridge:/root/.matterbridge' # Mounts the Matterbridge storage directory
      - '${HOME}/.mattercert:/root/.mattercert' # Mounts the Matterbridge certificate directory

Copy it to your home directory or edit your existing compose file to add the Matterbridge service.

Then start Docker Compose with:

docker compose pull matterbridge
docker compose up -d

Or start only the Matterbridge container with:

docker compose pull matterbridge
docker compose up -d matterbridge

If you need to start Matterbridge with extra parameters (e.g. frontend on port 8585), override the default command by adding a command line to the service:

services:
  matterbridge:
    ...
    command: ["matterbridge", "--docker", "--frontend", "8585"]

If you override the command, always start it with ["matterbridge", "--docker"].

If you change the frontend port (or enable https), overriding the default command of the images, docker will report the container unhealty unless you add:.

healthcheck:
  disable: true

Stop with Docker Compose

docker compose down

Update with Docker Compose

This pulls the new Matterbridge image and restarts only the Matterbridge container:

docker compose pull matterbridge
docker compose up -d --no-deps --force-recreate matterbridge

This pulls all images and restarts all containers:

docker compose pull
docker compose down
docker compose up -d

Inspect the container

docker container inspect matterbridge

Start the Docker container

docker start matterbridge

Stop the Docker container

docker stop matterbridge

Restart the Docker container

docker restart matterbridge

Show the logs

docker logs matterbridge

Show the logs for a time interval

docker logs \
  --since "2025-04-19T00:00:00" \
  --until "2025-04-19T00:02:00" \
  matterbridge

Show the logs in real time (tail)

docker logs --tail 1000 -f matterbridge

Prevent log growth

If you want to prevent Docker logs from growing too much, you can configure Docker's logging options globally.

Warning: This will restart Docker and affect all running containers.

sudo nano /etc/docker/daemon.json

Add or update the logging configuration in daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

Where:

• max-size: Maximum size of each log file (e.g., "10m", "100m", "1g")
• max-file: Maximum number of log files to keep

Save the file and restart Docker:

sudo systemctl restart docker

Note: This configuration applies to new containers. Existing containers must be recreated to use the new logging settings.

Run with Docker Desktop and mDNS Reflector on Windows

Windows (PowerShell) with Docker Desktop (us