matterbridge 3.2.0-dev-20250801-e5ebd91 → 3.2.0-dev-20250802-fb1e4d0

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
+```

package/docs/README-SERVICE.md

@@ -0,0 +1,212 @@
+# <img src="frontend/public/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px">&nbsp;&nbsp;&nbsp;Matterbridge systemd 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 as a daemon with systemctl (Linux only)
+
+The easiest way to add systemctl is to use [Matterbridge service cli for linux](https://github.com/Luligu/mb-service-linux).
+
+If your setup is too complex or you prefer to do it manually follow this method. You can still use mb-service to manage systemd after.
+
+### First create the Matterbridge directories
+
+This will create the required directories if they don't exist
+
+```bash
+cd ~
+mkdir -p ./Matterbridge
+mkdir -p ./.matterbridge
+sudo chown -R $USER:$USER ./Matterbridge ./.matterbridge
+```
+
+### Then create a systemctl configuration file for Matterbridge
+
+Create a systemctl configuration file for Matterbridge
+
+```bash
+sudo nano /etc/systemd/system/matterbridge.service
+```
+
+Add the following to this file, replacing 3 times (!) USER with your user name (e.g. WorkingDirectory=/home/pi/Matterbridge, User=pi and Group=pi):
+
+You may need to adapt the configuration to your setup:
+
+- execStart on some linux distribution can also be ExecStart==/usr/bin/matterbridge -service
+
+```
+[Unit]
+Description=matterbridge
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=matterbridge -service
+WorkingDirectory=/home/<USER>/Matterbridge
+StandardOutput=inherit
+StandardError=inherit
+Restart=always
+User=<USER>
+Group=<USER>
+
+[Install]
+WantedBy=multi-user.target
+```
+
+If you use the frontend with -ssl -frontend 443 and get an error message: "Port 443 requires elevated privileges",
+add this:
+
+```
+[Service]
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+```
+
+If you use the matterbridge-bthome plugin add this:
+
+```
+[Service]
+AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_NET_ADMIN
+```
+
+If you modify matterbridge.service after, then run:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart matterbridge.service
+```
+
+### Start Matterbridge
+
+```bash
+sudo systemctl start matterbridge
+```
+
+### Stop Matterbridge
+
+```bash
+sudo systemctl stop matterbridge
+```
+
+### Show Matterbridge status
+
+```bash
+sudo systemctl status matterbridge.service
+```
+
+### Enable Matterbridge to start automatically on boot
+
+```bash
+sudo systemctl enable matterbridge.service
+```
+
+### Disable Matterbridge from starting automatically on boot
+
+```bash
+sudo systemctl disable matterbridge.service
+```
+
+### View the log of Matterbridge in real time (this will show the log with colors)
+
+```bash
+sudo journalctl -u matterbridge.service -n 1000 -f --output cat
+```
+
+### Delete the logs older then 3 days (all of them not only the ones of Matterbridge!)
+
+Check the space used
+
+```bash
+sudo journalctl --disk-usage
+```
+
+remove all log older then 3 days
+
+```bash
+sudo journalctl --rotate
+sudo journalctl --vacuum-time=3d
+```
+
+## Prevent the journal logs to grow
+
+If you want to make the setting permanent to prevent the journal logs to grow too much, run
+
+```bash
+sudo nano /etc/systemd/journald.conf
+```
+
+add
+
+```bash
+Compress=yes            # Compress logs
+MaxRetentionSec=3days   # Keep logs for a maximum of 3 days.
+MaxFileSec=1day         # Rotate logs daily within the 3-day retention period.
+ForwardToSyslog=no      # Disable forwarding to syslog to prevent duplicate logging.
+SystemMaxUse=100M       # Limit persistent logs in /var/log/journal to 100 MB.
+RuntimeMaxUse=100M      # Limit runtime logs in /run/log/journal to 100 MB.
+```
+
+save it and run
+
+```bash
+sudo systemctl restart systemd-journald
+```
+
+## Verify that with your distro you can run sudo npm install -g matterbridge without the password
+
+Run the following command to verify if you can install Matterbridge globally without being prompted for a password:
+
+```bash
+sudo npm install -g matterbridge
+```
+
+If you are not prompted for a password, no further action is required.
+
+If that is not the case, open the sudoers file for editing using visudo
+
+```bash
+sudo visudo
+```
+
+verify the presence of of a line
+
+```
+@includedir /etc/sudoers.d
+```
+
+exit and create a configuration file for sudoers
+
+```bash
+sudo nano /etc/sudoers.d/matterbridge
+```
+
+add this line replacing USER with your user name (e.g. radxa ALL=(ALL) NOPASSWD: ALL)
+
+```
+<USER> ALL=(ALL) NOPASSWD: ALL
+```
+
+or if you prefers to only give access to npm without password try with (e.g. radxa ALL=(ALL) NOPASSWD: /usr/bin/npm)
+
+```
+<USER> ALL=(ALL) NOPASSWD: /usr/bin/npm
+```
+
+save the file and reload the settings with:
+
+```bash
+sudo chmod 0440 /etc/sudoers.d/matterbridge
+sudo visudo -c
+```