Matterbridge systemd configuration with private global node_modules

Advanced configuration

Run matterbridge as a daemon with systemctl (Linux only) with user matterbridge and private global node_modules

The advantage of this setup is that the global node_modules and npm cache are private for matterbridge and sudo is not required.

The service runs with group and user matterbridge and the system has full protection.

Important

The storage position is not compatible with the traditional setup (~/Matterbridge ~/.matterbridge ~/.mattercert).

Also various scripts don't work if you choose this configuration.

1 - Create the matterbridge user and group

# ✅ Create the matterbridge group
sudo groupadd --system matterbridge 2>/dev/null || true
# ✅ Create the matterbridge user
sudo useradd  --system \
  --home-dir /opt/matterbridge \
  --shell /usr/sbin/nologin \
  --gid matterbridge \
  matterbridge 2>/dev/null || true

2 - 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 2>/dev/null || true
# ✅ Safe precaution we need to uninstall from the global node_modules
sudo npm uninstall matterbridge -g 2>/dev/null || true
# ✅ Creates all required directories
sudo mkdir -p /opt/matterbridge /opt/matterbridge/Matterbridge /opt/matterbridge/.matterbridge /opt/matterbridge/.mattercert /opt/matterbridge/.npm-global /opt/matterbridge/.npm-cache
# ✅ Ensures ownership
sudo chown -R matterbridge:matterbridge /opt/matterbridge /opt/matterbridge/Matterbridge /opt/matterbridge/.matterbridge /opt/matterbridge/.mattercert /opt/matterbridge/.npm-global /opt/matterbridge/.npm-cache
# ✅ Secure permissions
sudo chmod -R 755 /opt/matterbridge /opt/matterbridge/Matterbridge /opt/matterbridge/.matterbridge /opt/matterbridge/.mattercert /opt/matterbridge/.npm-global /opt/matterbridge/.npm-cache
# make sure the “bin” dir exists for global executables
sudo -u matterbridge mkdir -p /opt/matterbridge/.npm-global/bin
# ✅ Install matterbridge in the private global node_modules using the private npm cache
sudo -u matterbridge npm install matterbridge --omit=dev --verbose --global --prefix=/opt/matterbridge/.npm-global --cache=/opt/matterbridge/.npm-cache
# ✅ Create a link to matterbridge bins
sudo ln -sf /opt/matterbridge/.npm-global/bin/matterbridge /usr/bin/matterbridge
sudo ln -sf /opt/matterbridge/.npm-global/bin/mb_mdns /usr/bin/mb_mdns
sudo ln -sf /opt/matterbridge/.npm-global/bin/mb_coap /usr/bin/mb_coap
# ✅ Clear bash command cache as a precaution
hash -r
# ✅ Check if matterbridge is /usr/bin/matterbridge
which matterbridge
# ✅ Will output the matterbridge version
matterbridge --version

The storage position is not compatible with the traditional setup (~/Matterbridge ~/.matterbridge ~/.mattercert).

If you are migrating from the traditional service setup, before removing the old diretories, you may want to copy the contents of ~/Matterbridge ~/.matterbridge ~/.mattercert to the new directories /opt/matterbridge/Matterbridge /opt/matterbridge/.matterbridge /opt/matterbridge/.mattercert. This will save all the plugin configs and the fabrics but you need to remove all plugins and readd them cause the path will be different.

Copy the old diretories content

sudo cp -a ~/Matterbridge/. /opt/matterbridge/Matterbridge/
sudo cp -a ~/.matterbridge/. /opt/matterbridge/.matterbridge/
sudo cp -a ~/.mattercert/. /opt/matterbridge/.mattercert/

Remove the old diretories

sudo rm -rf ~/Matterbridge ~/.matterbridge ~/.mattercert ~/.npm-global

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

[Unit]
Description=matterbridge
After=network.target
Wants=network.target

[Service]
Type=simple
Environment=NODE_ENV=production
Environment="NPM_CONFIG_PREFIX=/opt/matterbridge/.npm-global"
Environment="NPM_CONFIG_CACHE=/opt/matterbridge/.npm-cache"
ExecStart=matterbridge --service --nosudo
WorkingDirectory=/opt/matterbridge/Matterbridge
StandardOutput=inherit
StandardError=inherit
Restart=always
User=matterbridge
Group=matterbridge
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/opt/matterbridge

[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

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

Enable Matterbridge to start automatically on boot

sudo systemctl enable matterbridge

Disable Matterbridge from starting automatically on boot

sudo systemctl disable matterbridge

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

sudo journalctl -u matterbridge -n 1000 -f --output cat