Uptime-Kuma is a very useful tool. Besides being able to monitor whether services, websites, or ports are responding, it can also send notifications using many different services, even combined, and check the expiration of certificates. Additionally, it can create informative dashboards about the status of services.
I have been using it extensively for years, including for BSD Cafe. My initial deployments were on Docker containers, but recently, I have moved everything to FreeBSD jails.
When proceeding with the standard installation described in their documentation, the process will halt because one of the third-party libraries (Playwright) is not officially compatible with FreeBSD. However, since this library is not necessary for the type of checks I want to perform (I am not interested in checking web page components, just their response), it is possible to continue and run everything using a small hack.
It can be installed directly on FreeBSD but, in my case, I prefer using jails. Note that if using traditional jails (i.e., not VNet), "ping" is disabled. Therefore, if using traditional jails and wanting to check hosts via ping, it is advisable to add the line allow.raw_sockets; to the respective jail.conf.
The installation can proceed as follows:
The first step is to install the necessary dependencies:
pkg install node20 npm-node20 git-lite
Once the dependencies are installed, it is advisable to create a user to run everything and use that user for the next steps:
pw add user ukuma -m
echo 'export LC_ALL="en_US.UTF-8"' >> /home/ukuma/.profile
su -l ukuma
At this point, clone the Uptime-Kuma repository and start installing the dependencies:
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma/
npm run setup
The operation will seem to complete correctly. However, running the program will result in a fatal error preventing it from functioning:
ukuma@ukuma:~/uptime-kuma $ node server/server.js
[...]
/home/ukuma/uptime-kuma/node_modules/playwright-core/lib/server/registry/index.js:258
if (process.platform === 'linux') cacheDirectory = process.env.XDG_CACHE_HOME || _path.default.join(os.homedir(), '.cache'); else if (process.platform === 'darwin') cacheDirectory = _path.default.join(os.homedir(), 'Library', 'Caches'); else if (process.platform === 'win32') cacheDirectory = process.env.LOCALAPPDATA || _path.default.join(os.homedir(), 'AppData', 'Local'); else throw new Error('Unsupported platform: ' + process.platform);
^
Error: Unsupported platform: freebsd
at /home/ukuma/uptime-kuma/node_modules/playwright-core/lib/server/registry/index.js:258:388
at Object.<anonymous> (/home/ukuma/uptime-kuma/node_modules/playwright-core/lib/server/registry/index.js:270:3)
at Module._compile (node:internal/modules/cjs/loader:1369:14)
at Module._extensions..js (node:internal/modules/cjs/loader:1427:10)
at Module.load (node:internal/modules/cjs/loader:1206:32)
at Module._load (node:internal/modules/cjs/loader:1022:12)
at Module.require (node:internal/modules/cjs/loader:1231:19)
at require (node:internal/modules/helpers:179:18)
at Object.<anonymous> (/home/ukuma/uptime-kuma/node_modules/playwright-core/lib/server/index.js:84:17)
at Module._compile (node:internal/modules/cjs/loader:1369:14)
The issue is clear: Playwright does not support FreeBSD, causing the operation to fail. At this point, there are two options:
- Hope that Microsoft decides to support FreeBSD, which is unlikely in the short term.
- Trick Playwright into thinking FreeBSD is supported, which may break some related functionality, but it is a small price to pay to have all other features of Uptime-Kuma.
I will use the second method. Open the indicated file (in this case, /home/ukuma/uptime-kuma/node_modules/playwright-core/lib/server/registry/index.js) and modify the indicated line (in this case, 258). Change the line if (process.platform === 'linux') to if (process.platform === 'freebsd') and save it.
Uptime-Kuma will then be able to import the necessary libraries and function, listening on port 3001.
At this point, it will be possible to use it normally, as well as use pm2 to start and manage it automatically, but this goes beyond the scope of this article.