matterbridge
Version:
Matterbridge plugin manager for Matter
241 lines (181 loc) • 8.64 kB
Markdown
<!-- eslint-disable markdown/no-missing-label-refs -->
<!-- eslint-disable markdown/no-multiple-h1 -->
# <img src="https://matterbridge.io/assets/matterbridge.svg" alt="Matterbridge Logo" width="64px" height="64px"> Matterbridge systemd configuration with local global node_modules
[](https://www.npmjs.com/package/matterbridge)
[](https://www.npmjs.com/package/matterbridge)
[](https://hub.docker.com/r/luligu/matterbridge)
[](https://hub.docker.com/r/luligu/matterbridge)
[](https://codecov.io/gh/Luligu/matterbridge)
[](https://vitest.dev)
[](https://oxc.rs/docs/guide/usage/formatter.html)
[](https://oxc.rs/docs/guide/usage/linter.html)
[](https://www.typescriptlang.org/)
[](https://github.com/microsoft/typescript-go)
[](https://nodejs.org/)
[](https://bun.com)
[](https://matterbridge.io)
[](https://www.npmjs.com/package/matter-history)
[](https://www.npmjs.com/package/node-ansi-logger)
[](https://www.npmjs.com/package/node-persist-manager)
---
# Production advanced configuration
> **Nvm is a development tool and is not supported for production**.
## Run matterbridge as a daemon with systemctl (Linux only) with local global node_modules
The advantage of this setup is that the global node_modules and npm cache are private for the user and sudo is not required.
The service runs rootless like the current user.
The storage position is compatible with the traditional setup (~/Matterbridge ~/.matterbridge ~/.mattercert).
Other scripts don't work if you choose this configuration.
### First create the Matterbridge directories and set the correct permissions
This will create the required directories if they don't exist
```bash
cd ~
# ✅ Safe precaution if matterbridge was already running with the traditional setup
sudo systemctl stop matterbridge
# ✅ We need to uninstall from the global node_modules
sudo npm uninstall matterbridge -g
# ✅ Creates all needed dirs
mkdir -p ~/Matterbridge ~/.matterbridge ~/.mattercert ~/.npm-global ~/.npm-cache
# ✅ Ensures ownership
chown -R $USER:$USER ~/Matterbridge ~/.matterbridge ~/.mattercert ~/.npm-global ~/.npm-cache
# ✅ Secure permissions
chmod -R 755 ~/Matterbridge ~/.matterbridge ~/.mattercert ~/.npm-global ~/.npm-cache
# ✅ Install matterbridge in the local global node_modules, with the local cache and no sudo
npm install matterbridge --omit=dev --verbose --global --prefix=~/.npm-global --cache=~/.npm-cache
# ✅ Create a link to matterbridge bin
sudo ln -sf /home/$USER/.npm-global/bin/matterbridge /usr/local/bin/matterbridge
# ✅ Create a link to mb-health bin
sudo ln -sf /home/$USER/.npm-global/bin/mb-health /usr/local/bin/mb-health
# ✅ Create a link to mb-mdns bin
sudo ln -sf /home/$USER/.npm-global/bin/mb-mdns /usr/local/bin/mb-mdns
# ✅ Create a link to mb-coap bin
sudo ln -sf /home/$USER/.npm-global/bin/mb-coap /usr/local/bin/mb-coap
# ✅ Clear bash command cache as a precaution
hash -r
# ✅ Check which matterbridge
which matterbridge
# ✅ Will output the matterbridge version
matterbridge --version
```
### 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 5 times (!) USER with your user name** (e.g. WorkingDirectory=/home/pi/Matterbridge, User=pi and Group=pi, Environment="NPM_CONFIG_PREFIX=/home/pi/.npm-global" and Environment="NPM_CONFIG_CACHE=/home/pi/.npm-cache"):
```text
[Unit]
Description=matterbridge
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=60
StartLimitBurst=5
[Service]
Type=simple
Environment="NPM_CONFIG_PREFIX=/home/<USER>/.npm-global"
Environment="NPM_CONFIG_CACHE=/home/<USER>/.npm-cache"
ExecStart=matterbridge --service --nosudo
WorkingDirectory=/home/<USER>/Matterbridge
# Logs go to the journal (should be persistent). Read with: journalctl -u matterbridge -n 1000 -f --output cat
StandardOutput=journal
StandardError=journal
SyslogIdentifier=matterbridge
Restart=always
RestartSec=5
TimeoutStopSec=60
User=<USER>
Group=<USER>
[Install]
WantedBy=multi-user.target
```
On some systems, npm install may fail with errors like `ENETUNREACH`:
This happens when:
The system has IPv6 enabled
DNS returns IPv6 (AAAA) records
But the host does not have a working IPv6 default route
In this situation:
Node.js may try IPv6 first.
The connection fails with ENETUNREACH.
Npm retries may randomly succeed or fail depending on resolution order.
This often indicates a misconfigured IPv6 route / DNS preference.
One possible fix, add this line to the existing [Service] section:
```text
Environment="NODE_OPTIONS=--dns-result-order=ipv4first"
```
If you use the frontend with --ssl --frontend 443 and get an error message: "Port 443 requires elevated privileges",
add this line to the existing [Service] section:
```text
AmbientCapabilities=CAP_NET_BIND_SERVICE
```
If you use the matterbridge-bthome plugin add this line to the existing [Service] section:
```text
AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_NET_ADMIN
```
Now and if you modify matterbridge.service after, run:
```bash
sudo systemctl daemon-reload
sudo systemctl restart matterbridge.service
sudo systemctl status 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 than 3 days (all of them not only the ones of Matterbridge!)
Check the space used
```bash
sudo journalctl --disk-usage
```
remove all log older than 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 these to the [Journal] section:
```bash
# Store logs persistently in /var/log/journal so they survive reboots.
Storage=persistent
# Compress logs to save space.
Compress=yes
# Keep logs for a maximum of 3 days.
MaxRetentionSec=3days
# Rotate logs daily within the 3-day retention period.
MaxFileSec=1day
# Disable forwarding to syslog to prevent duplicate logging.
ForwardToSyslog=no
# Limit persistent (disk) logs in /var/log/journal to 100 MB.
SystemMaxUse=100M
# Limit runtime (memory) logs in /run/log/journal to 100 MB.
RuntimeMaxUse=100M
```
save it and check if other configs override yours:
```bash
sudo systemctl restart systemd-journald
sudo systemd-analyze cat-config systemd/journald.conf
```