Matterbridge systemd configuration with local global node_modules

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

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

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"):

[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:

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:

AmbientCapabilities=CAP_NET_BIND_SERVICE

If you use the matterbridge-bthome plugin add this line to the existing [Service] section:

AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_NET_ADMIN

Now and if you modify matterbridge.service after, run:

sudo systemctl daemon-reload
sudo systemctl restart matterbridge.service
sudo systemctl status matterbridge.service

Start Matterbridge

sudo systemctl start matterbridge

Stop Matterbridge

sudo systemctl stop matterbridge

Show Matterbridge status

sudo systemctl status matterbridge.service

Enable Matterbridge to start automatically on boot

sudo systemctl enable matterbridge.service

Disable Matterbridge from starting automatically on boot

sudo systemctl disable matterbridge.service

View the log of Matterbridge in real time (this will show the log with colors)

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

sudo journalctl --disk-usage

remove all log older than 3 days

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

sudo nano /etc/systemd/journald.conf

add these to the [Journal] section:

# 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:

sudo systemctl restart systemd-journald
sudo systemd-analyze cat-config systemd/journald.conf