matterbridge 3.2.0-dev-20250801-e5ebd91 → 3.2.0

package/docs/README-DOCKER.md

@@ -0,0 +1,208 @@
+# <img src="frontend/public/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px">&nbsp;&nbsp;&nbsp;Matterbridge docker configuration
+
+[![npm version](https://img.shields.io/npm/v/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![npm downloads](https://img.shields.io/npm/dt/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
+![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
+![CodeQL](https://github.com/Luligu/matterbridge/actions/workflows/codeql.yml/badge.svg)
+[![codecov](https://codecov.io/gh/Luligu/matterbridge/branch/main/graph/badge.svg)](https://codecov.io/gh/Luligu/matterbridge)
+
+[![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
+[![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
+[![power by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
+
+---
+
+# Advanced configuration
+
+## Run matterbridge with docker and docker compose
+
+The Matterbridge Docker image, which includes a manifest list for the linux/amd64, linux/arm64 and linux/arm/v7 architectures, is published on **Docker Hub**.
+
+The image (tag **latest**) includes matterbridge and all official plugins with the latest release (as published on npm). You can just pull the new image and matterbridge with all plugins will be the latest release published on npm.
+
+The image (tag **dev**) includes matterbridge and all plugins with the dev release (as pushed on GitHub). You can just pull the new image and matterbridge with all plugins will be the latest dev release pushed on GitHub. It is possible that the devs are outdated by published latests.
+
+You can directly select and add a plugin without installing it.
+
+It is based on node:22-bookworm-slim and integrates the health check.
+
+How Health Checks Work in Different Scenarios
+
+With docker-compose
+
+Docker monitors the health check and can restart the container if needed.
+
+With docker run
+
+The health check still runs in the background, but:
+The container doesn’t restart automatically if it becomes unhealthy.
+
+You can manually check the health status:
+
+```bash
+docker exec -it matterbridge curl -v http://localhost:8283/health
+```
+
+### First create the Matterbridge directories
+
+This will create the required directories in your home directory if they don't exist
+
+```bash
+cd ~
+mkdir -p ~/Matterbridge
+mkdir -p ~/.matterbridge
+sudo chown -R $USER:$USER ~/Matterbridge ~/.matterbridge
+```
+
+You may need to adapt the script to your setup.
+
+### Add your user to docker group
+
+If you don't want to use sudo with docker commands, run this command:
+
+```bash
+sudo groupadd docker
+sudo usermod -aG docker $USER
+```
+
+After adding your user to the docker group, you need to log out and log back in for the changes to take effect. This ensures that your current session recognizes the group membership change.
+
+### Run the Docker container and start it
+
+The container must have full access to the host network (needed for mdns and Matter protocol).
+
+```bash
+sudo docker run --name matterbridge \
+  -v ~/Matterbridge:/root/Matterbridge \
+  -v ~/.matterbridge:/root/.matterbridge \
+  --network host --restart always -d luligu/matterbridge:latest
+```
+
+You may need to adapt the script to your setup.
+
+### Run with docker compose
+
+The docker-compose.yml file is available in the docker directory of the package
+
+```
+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
+    volumes:
+      - "${HOME}/Matterbridge:/root/Matterbridge"             # Mounts the Matterbridge plugin directory
+      - "${HOME}/.matterbridge:/root/.matterbridge"           # Mounts the Matterbridge storage directory
+```
+
+Copy it in the home directory or edit the existing one to add the matterbridge service.
+
+Then start docker compose with:
+
+```bash
+docker compose up -d
+```
+
+or start only the matterbridge container with:
+
+```bash
+docker compose up -d matterbridge
+```
+
+### Stop with docker compose
+
+```bash
+docker compose down
+```
+
+### Update with docker compose
+
+This will pull the new matterbridge image and restart only the matterbridge container.
+
+```bash
+docker compose pull matterbridge
+docker compose up -d --no-deps --force-recreate matterbridge
+```
+
+### Inspect the container
+
+```bash
+docker container inspect matterbridge
+```
+
+### Start the Docker container
+
+```bash
+docker start matterbridge
+```
+
+### Stop the Docker container
+
+```bash
+docker stop matterbridge
+```
+
+### Restart the Docker container
+
+```bash
+docker restart matterbridge
+```
+
+### Shows the logs
+
+```bash
+docker logs matterbridge
+```
+
+### Shows the logs for a time interval
+
+```bash
+docker logs \
+  --since "2025-04-19T00:00:00" \
+  --until "2025-04-19T00:02:00" \
+  matterbridge
+```
+
+### Shows the logs real time (tail)
+
+```bash
+docker logs --tail 1000 -f matterbridge
+```
+
+### Prevent the logs to grow
+
+If you want to prevent the docker logs to grow too much, you can configure Docker's logging options globally.
+
+**Warning**: This will restart Docker and affect all running containers.
+
+```bash
+sudo nano /etc/docker/daemon.json
+```
+
+Add or update the logging configuration in the daemon.json file:
+
+```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:
+
+```bash
+sudo systemctl restart docker
+```
+
+**Note**: This configuration applies to new containers. Existing containers will need to be recreated to use the new logging settings.

package/docs/README-NGINX.md

@@ -0,0 +1,235 @@
+# <img src="frontend/public/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px">&nbsp;&nbsp;&nbsp;Matterbridge NGINX configuration
+
+[![npm version](https://img.shields.io/npm/v/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![npm downloads](https://img.shields.io/npm/dt/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
+![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
+![CodeQL](https://github.com/Luligu/matterbridge/actions/workflows/codeql.yml/badge.svg)
+[![codecov](https://codecov.io/gh/Luligu/matterbridge/branch/main/graph/badge.svg)](https://codecov.io/gh/Luligu/matterbridge)
+
+[![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
+[![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
+[![power by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
+
+---
+
+# Advanced configuration to use NGINX
+
+## Run matterbridge with nginx
+
+### Create a basic nginx configuration file that redirect to http://yourhost:8283
+
+```
+sudo nano /etc/nginx/sites-available/matterbridge
+```
+
+paste this configuration and if desired change the port to listen (here is 80) and the server_name using yours:
+
+```
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+
+    location / {
+        # Redirect to Matterbridge frontend from http:/server_name:80
+        proxy_pass http://localhost:8283/;
+        proxy_set_header Host                 $host;
+        proxy_set_header X-Real-IP            $remote_addr;
+        proxy_set_header X-Forwarded-For      $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto    $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade              $http_upgrade;
+        proxy_set_header Connection           $http_connection;
+    }
+}
+```
+
+Add matterbridge to enabled sites
+
+```bash
+sudo ln -s /etc/nginx/sites-available/matterbridge /etc/nginx/sites-enabled/
+```
+
+### Create a basic nginx configuration file that redirect to http://yourhost:8283/matterbridge
+
+```bash
+sudo nano /etc/nginx/sites-available/matterbridge
+```
+
+paste this configuration and if desired change the port to listen (here is 80) and the server_name using yours:
+
+```
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+
+    location /matterbridge/ {
+        # Redirect to Matterbridge frontend from http:/server_name/matterbridge:80
+        proxy_pass http://localhost:8283/;
+        proxy_set_header Host                     $host;
+        proxy_set_header X-Real-IP                $remote_addr;
+        proxy_set_header X-Forwarded-For          $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto        $scheme;
+
+        # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade                  $http_upgrade;
+        proxy_set_header Connection               $http_connection;
+    }
+}
+```
+
+Add matterbridge to enabled sites
+
+```bash
+sudo ln -s /etc/nginx/sites-available/matterbridge /etc/nginx/sites-enabled/
+```
+
+Restart nginx and test the configuration
+
+```bash
+sudo systemctl restart nginx
+sudo nginx -t
+```
+
+### Create an advanced nginx configuration file that redirect to http://yourhost:8283 with ssl
+
+```bash
+sudo nano /etc/nginx/sites-available/matterbridge
+```
+
+paste this configuration adding your certificates:
+
+```
+# Default server configuration
+
+# Redirect all HTTP requests to HTTPS
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+
+    return 301 https://$host$request_uri;
+}
+
+# HTTPS server configuration
+server {
+    listen 443 ssl default_server;
+      listen [::]:443 ssl default_server;
+    http2 on;
+    server_name _;
+
+    # SSL certificate paths
+    ssl_certificate /etc/nginx/certs/cert.pem;
+    ssl_certificate_key /etc/nginx/certs/key.pem;
+
+    # SSL security settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    location / {
+      # Redirect to Matterbridge frontend from https:/server_name:443
+      proxy_pass http://localhost:8283/;
+      proxy_set_header Host                 $host;
+      proxy_set_header X-Real-IP            $remote_addr;
+      proxy_set_header X-Forwarded-For      $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto    $scheme;
+
+      # WebSocket support
+      proxy_http_version 1.1;
+      proxy_set_header Upgrade              $http_upgrade;
+      proxy_set_header Connection           $http_connection;
+    }
+}
+```
+
+Add matterbridge to enabled sites
+
+```bash
+sudo ln -s /etc/nginx/sites-available/matterbridge /etc/nginx/sites-enabled/
+```
+
+Restart nginx and test the configuration
+
+```bash
+sudo systemctl restart nginx
+sudo nginx -t
+```
+
+### Create an advanced nginx configuration file that redirect to http://yourhost/matterbridge with ssl
+
+```bash
+sudo nano /etc/nginx/sites-available/matterbridge
+```
+
+paste this configuration adding your certificates:
+
+```
+# Redirect all HTTP requests to HTTPS
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+
+    return 301 https://$host$request_uri;
+}
+
+# HTTPS server configuration
+server {
+	listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+	http2 on;
+	server_name _;
+
+	# SSL certificate paths
+    ssl_certificate /etc/nginx/certs/cert.pem;
+    ssl_certificate_key /etc/nginx/certs/key.pem;
+
+    # SSL security settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+	root /var/www/html;
+	index index.html index.htm index.nginx-debian.html;
+
+	location / {
+		# First attempt to serve request as file, then
+		# as directory, then fall back to displaying a 404.
+		try_files $uri $uri/ =404;
+	}
+
+    location /matterbridge/ {
+	    # Redirect to Matterbridge frontend from https:/server_name/matterbridge:443
+        proxy_pass http://localhost:8283/;
+        proxy_set_header Host                       $host;
+        proxy_set_header X-Real-IP                  $remote_addr;
+        proxy_set_header X-Forwarded-For            $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto          $scheme;
+
+	    # WebSocket support
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade                    $http_upgrade;
+        proxy_set_header Connection                 $http_connection;
+    }
+}
+```
+
+Add matterbridge to enabled sites
+
+```bash
+sudo ln -s /etc/nginx/sites-available/matterbridge /etc/nginx/sites-enabled/
+```
+
+Restart nginx and test the configuration
+
+```bash
+sudo systemctl restart nginx
+sudo nginx -t
+```

package/docs/README-PODMAN.md

@@ -0,0 +1,109 @@
+# <img src="frontend/public/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px">&nbsp;&nbsp;&nbsp;Matterbridge Podman configuration
+
+[![npm version](https://img.shields.io/npm/v/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![npm downloads](https://img.shields.io/npm/dt/matterbridge.svg)](https://www.npmjs.com/package/matterbridge)
+[![Docker Version](https://img.shields.io/docker/v/luligu/matterbridge?label=docker%20version&sort=semver)](https://hub.docker.com/r/luligu/matterbridge)
+[![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge.svg)](https://hub.docker.com/r/luligu/matterbridge)
+![Node.js CI](https://github.com/Luligu/matterbridge/actions/workflows/build.yml/badge.svg)
+![CodeQL](https://github.com/Luligu/matterbridge/actions/workflows/codeql.yml/badge.svg)
+[![codecov](https://codecov.io/gh/Luligu/matterbridge/branch/main/graph/badge.svg)](https://codecov.io/gh/Luligu/matterbridge)
+
+[![power by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history)
+[![power by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger)
+[![power by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](https://www.npmjs.com/package/node-persist-manager)
+
+---
+
+# Advanced configuration
+
+## Install Podman if it is not already installed
+
+```
+cd ~
+sudo apt update
+sudo apt install podman -y
+podman --version
+```
+
+## Run matterbridge with podman
+
+The Matterbridge Docker image, which includes a manifest list for the linux/amd64, linux/arm64 and linux/arm/v7 architectures, is published on Docker Hub and can be used with podman.
+
+Podman handles container restarts a little differently than Docker. The --restart always flag doesn’t work exactly the same. If you want the container to automatically restart when the system reboots or if it crashes, you can create a systemd unit for the Podman container.
+
+### First create the Matterbridge directories
+
+This will create the required directories if they don't exist
+
+```
+cd ~
+mkdir -p ./Matterbridge
+mkdir -p ./.matterbridge
+sudo chown -R $USER:$USER ./Matterbridge ./.matterbridge
+```
+
+You may need to adapt the script to your setup:
+
+- ./Matterbridge is the position outside of the container of your matterbridge plugin directory (inside your home directory).
+- ./.matterbridge is the position outside of the container of your matterbridge storage directory (inside your home directory).
+
+### Run the Podman container (root mode) and start it
+
+The container must have full access to the host network (needed for matter mdns).
+
+```
+podman run --name matterbridge \
+  -v ~/Matterbridge:/root/Matterbridge \
+  -v ~/.matterbridge:/root/.matterbridge \
+  --network host --restart always -d docker.io/luligu/matterbridge:latest
+```
+
+You may need to adapt the script to your setup:
+
+- ~/Matterbridge is the position outside of the container of your matterbridge plugin directory.
+- ~/.matterbridge is the position outside of the container of your matterbridge storage directory.
+
+### Integrate the mattebridge podman container with systemd for automatic startup after reboots
+
+```
+podman generate systemd --name matterbridge --files --new
+sudo mv container-matterbridge.service /etc/systemd/system/
+sudo systemctl enable container-matterbridge
+sudo systemctl start container-matterbridge
+```
+
+### Start the Podman container
+
+```
+podman start matterbridge
+```
+
+### Stop the Podman container
+
+```
+podman stop matterbridge
+```
+
+### Restart the Podman container
+
+```
+podman restart matterbridge
+```
+
+### Remove the Podman container
+
+```
+podman rm matterbridge
+```
+
+### Shows the logs
+
+```
+podman logs matterbridge
+```
+
+### Shows the logs real time (tail)
+
+```
+podman logs --tail 1000 -f matterbridge
+```