# Matterbridge Logo   Matterbridge systemd configuration with private global node_modules [![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/latest?label=docker%20version)](https://hub.docker.com/r/luligu/matterbridge) [![Docker Pulls](https://img.shields.io/docker/pulls/luligu/matterbridge?label=docker%20pulls)](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) [![styled with prettier](https://img.shields.io/badge/styled_with-Prettier-f8bc45.svg?logo=prettier)](https://prettier.io/) [![linted with eslint](https://img.shields.io/badge/linted_with-ES_Lint-4B32C3.svg?logo=eslint)](https://eslint.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![ESM](https://img.shields.io/badge/ESM-Node.js-339933?logo=node.js&logoColor=white)](https://nodejs.org/) [![matterbridge.io](https://img.shields.io/badge/matterbridge.io-online-brightgreen)](https://matterbridge.io) [![powered by](https://img.shields.io/badge/powered%20by-matter--history-blue)](https://www.npmjs.com/package/matter-history) [![powered by](https://img.shields.io/badge/powered%20by-node--ansi--logger-blue)](https://www.npmjs.com/package/node-ansi-logger) [![powered by](https://img.shields.io/badge/powered%20by-node--persist--manager-blue)](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 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 ```bash # ✅ 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 ```bash 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 ```bash 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 ```bash sudo rm -rf ~/Matterbridge ~/.matterbridge ~/.mattercert ~/.npm-global ``` ### 3 - 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: ``` [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 ``` 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: ``` [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: ```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 ``` ### Enable Matterbridge to start automatically on boot ```bash sudo systemctl enable matterbridge ``` ### Disable Matterbridge from starting automatically on boot ```bash sudo systemctl disable matterbridge ``` ### View the log of Matterbridge in real time (this will show the log with colors) ```bash sudo journalctl -u matterbridge -n 1000 -f --output cat ```