This post covers a simple Wiki.js 2.5.314 installation on FreeBSD 15.1 using SQLite, Node.js 24, and a native rc.d service.

Setup

The jail is a normal FreeBSD 15.1-RELEASE jail with its own IP on the LAN.

FreeBSD 15.1-RELEASE Host
│
└── wiki jail
    └── Wiki.js :3000

No Docker or Linux emulation is needed. Wiki.js itself runs natively under FreeBSD Node.js.

Installing Wiki.js

I created a small bootstrap script which handles the whole installation.

Inside the jail as root:

fetch https://codeberg.org/dkade/BSD/raw/branch/main/FreeBSD/wikijs/install-wikijs-freebsd-15.1.sh
chmod +x install-wikijs-freebsd-15.1.sh
./install-wikijs-freebsd-15.1.sh

The script installs:

node24
npm-node24
python311
gmake
pkgconf
sqlite3
ca_root_nss

It then downloads Wiki.js 2.5.314 and extracts it under:

/usr/local/wikijs

A dedicated wikijs user is created to run the service instead of running Wiki.js as root.

The SQLite FreeBSD gotcha

The official Wiki.js release includes its node_modules, including a prebuilt sqlite3 native module.

Trying to start it directly on FreeBSD results in errors such as:

Shared object "libc.musl-x86_64.so.1" not found,
required by "node_sqlite3.node"

Running ldd makes the problem obvious:

ldd /usr/local/wikijs/node_modules/sqlite3/build/Release/node_sqlite3.node

returns:

not a FreeBSD ELF shared object

The bundled module is a Linux/musl binary, so it cannot be used natively on FreeBSD.

The solution is to rebuild only the SQLite native module:

cd /usr/local/wikijs

rm -rf node_modules/sqlite3/build

env \
  npm_config_python=/usr/local/bin/python3.11 \
  npm_config_build_from_source=true \
  MAKE=gmake \
  npm rebuild sqlite3

Python 3.11 is used because the version of node-gyp bundled with Wiki.js 2.5.x still depends on Python’s old distutils module, which was removed in Python 3.12.

After the rebuild:

file node_modules/sqlite3/build/Release/node_sqlite3.node

should identify it as a FreeBSD ELF shared object.

Test it directly:

node -e "const s=require('sqlite3'); console.log(s.VERSION); console.log('sqlite3 OK')"

Configuration

Wiki.js uses:

/usr/local/wikijs/config.yml

For a simple SQLite setup:

port: 3000

db:
  type: sqlite
  storage: /usr/local/wikijs/data/wiki.db

Make sure the database directory is writable by the Wiki.js user:

mkdir -p /usr/local/wikijs/data
chown -R wikijs:wikijs /usr/local/wikijs

FreeBSD rc.d service

The installer creates:

/usr/local/etc/rc.d/wikijs

Wiki.js is started using FreeBSD’s daemon(8) and Node.js:

/usr/local/bin/node /usr/local/wikijs/server

The service is enabled with:

sysrc wikijs_enable=YES

Start it:

service wikijs start

Check the status:

service wikijs status

Restart it:

service wikijs restart

Logs are written to:

/var/log/wikijs.log

so they can be followed with:

tail -f /var/log/wikijs.log

Once running, Wiki.js is available at:

http://<jail-ip>:3000

The first connection opens the Wiki.js setup wizard.

Upgrading

Before upgrading, take a ZFS snapshot or at least back up:

/usr/local/wikijs/config.yml
/usr/local/wikijs/data/

After replacing the Wiki.js application files with a newer release, rebuild the SQLite module again:

cd /usr/local/wikijs

env \
  npm_config_python=/usr/local/bin/python3.11 \
  npm_config_build_from_source=true \
  MAKE=gmake \
  npm rebuild sqlite3

Then restart Wiki.js:

service wikijs restart

Avoid blindly running:

npm update

or:

npm audit fix --force

inside the Wiki.js application tree. Wiki.js ships with a specific dependency set and changing package versions independently can break the application.

Gotchas

• SQLite native module: the bundled node_sqlite3.node is Linux/musl and must be rebuilt for FreeBSD.
• Python version: use Python 3.11 when rebuilding with the older bundled node-gyp.
• Node.js: Wiki.js 2.5.314 runs correctly with the FreeBSD node24 package.
• Do not copy old node_modules: when upgrading, use a clean Wiki.js release tree and preserve only your configuration and database.
• rc.d PID tracking: when using daemon(8), set procname to /usr/local/bin/node so service wikijs status correctly detects the running process.

Summary

Wiki.js runs cleanly inside a FreeBSD 15.1 jail without Docker or Linux emulation.

The only non-obvious part is rebuilding the bundled SQLite native module for FreeBSD. Once that is done, Wiki.js behaves like any other native FreeBSD service: a dedicated user, an rc.d script, automatic startup, and straightforward ZFS snapshots for backups and upgrades.

The bootstrap script automates the complete process from a fresh jail.

Architecture

FreeBSD 15.1-RELEASE Host
│
├── homeassistant (192.168.2.50)  — HA Core :8123
├── mosquitto    (192.168.2.52)  — MQTT broker :1883
└── zigbee2mqtt  (192.168.2.51)  — Zigbee2MQTT, Sonoff USB passthrough

All three jails are VNET on the same /24 subnet. HA Core talks to Mosquitto over MQTT, Zigbee2MQTT publishes device states to Mosquitto, and HA subscribes. Shelly devices connect directly over WiFi and are auto-discovered by HA on the LAN.

Why jails?

• Native FreeBSD — no Docker overlay, no Linux emulation
• VNET gives each jail a real IP on the LAN — devices discover HA directly
• ZFS snapshots for quick rollbacks before upgrades
• Each service in its own jail — clean isolation, restart one without affecting others

Creating the jails

bastille create -V homeassistant 15.1-RELEASE 192.168.2.50/24 vtnet0
bastille create -V mosquitto 15.1-RELEASE 192.168.2.52/24 vtnet0
bastille create -V zigbee2mqtt 15.1-RELEASE 192.168.2.51/24 vtnet0

The -V flag gives each jail a VNET interface with its own IP and routing table — they live on the same broadcast domain as the host.

HomeAssistant jail

A bootstrap script handles the full setup:

• Repository: codeberg.org/dkade/BSD
• Method: Python 3.14 virtual environment under /usr/local/etc/homeassistant/venv
• User: dedicated hass system user
• Service: FreeBSD rc.d script using daemon -u hass
• Enable: sysrc homeassistant_enable=YES

What the script does:

# Inside the jail as root
fetch https://codeberg.org/dkade/BSD/raw/branch/main/FreeBSD/install_ha_freebsd.sh
sh install_ha_freebsd.sh

It installs system packages (python314, gcc12, rust, dbus, libffi, openssl, etc.), creates a venv, and installs homeassistant along with numpy, zlib_ng, and isal for performance. The rc.d script starts HA as the hass user and listens on port 8123.

After first boot, complete the onboarding at http://192.168.2.50:8123.

Mosquitto jail

bastille console mosquitto
pkg install mosquitto
sysrc mosquitto_enable=YES
service mosquitto start

No authentication is needed on a local subnet — configure listener 1883 192.168.2.52 in /usr/local/etc/mosquitto/mosquitto.conf to bind to the jail IP.

Zigbee2MQTT jail

This jail needs access to the Sonoff Zigbee coordinator plugged into the host.

USB passthrough with devfs

On the host (/etc/devfs.rules):

[bastille_usb=101]
add path 'usbctl' mode 0660
add path 'usb/*' mode 0660
add path 'ugen*' mode 0660
add path 'cuaU*' mode 0660
add path 'ttyU*' mode 0660

Set the rule in /usr/local/bastille/jails/zigbee2mqtt/jail.conf:

devfs_ruleset = "bastille_usb";

Then find the Sonoff device:

# On the host
ls /dev/cuaU*
# /dev/cuaU0 <- this is the Sonoff

Restart the jail and you should see the device inside:

bastille restart zigbee2mqtt
bastille console zigbee2mqtt
ls /dev/cuaU*

Installing and configuring

bastille console zigbee2mqtt
pkg install node npm mosquitto-libs
npm install -g zigbee2mqtt

Create /usr/local/etc/zigbee2mqtt/configuration.yaml:

mqtt:
  server: mqtt://192.168.2.52:1883
serial:
  port: /dev/cuaU0
frontend:
  port: 8080

rc.d script at /usr/local/etc/rc.d/zigbee2mqtt to start via daemon, then sysrc zigbee2mqtt_enable=YES && service zigbee2mqtt start.

Device integration

• Shelly (WiFi): connect them to your WiFi. HA auto-discovers them via the LAN once the Shelly integration is added in the UI.
• Zigbee (Sonoff sensors, bulbs, etc.): pair through the Zigbee2MQTT frontend (http://192.168.2.51:8080). HA receives device states via MQTT auto-discovery.

Upgrading

# HA Core
bastille console homeassistant
service homeassistant stop
su -l hass -c \
  'HOME=/usr/local/etc/homeassistant PIP_CACHE_DIR=/tmp/pip-cache \
   /usr/local/etc/homeassistant/venv/bin/pip install --upgrade homeassistant'
service homeassistant start

# zigbee2mqtt
bastille console zigbee2mqtt
service zigbee2mqtt stop
npm update -g zigbee2mqtt
service zigbee2mqtt start

# mosquitto
bastille console mosquitto
pkg upgrade mosquitto
service mosquitto restart

Gotchas

• Python compilation: HA Core compiles C and Rust extensions during pip install. Make sure gcc12, rust, libffi, and openssl are installed in the jail before installing HA.
• dbus: HA Core expects D-Bus to be running (service dbus start). The rc.d script has REQUIRE: dbus, so dbus starts first.
• USB devfs: The devfs ruleset must be applied before the jail starts. Double-check the ruleset number matches in both /etc/devfs.rules and the jail config.
• VNET routing: If jails can’t reach the internet for pkg install, check that gateway_enable="YES" is set on the host and NAT/pf is configured for the VNET subnet.
• Persistent pip cache: The script sets PIP_CACHE_DIR=/tmp/pip-cache so you don’t re-download wheels on every upgrade.

Summary

Three FreeBSD jails managed with BastilleBSD running HA Core, Mosquitto, and Zigbee2MQTT — each with its own IP, rc.d service, and clean isolation. The bootstrap script at codeberg.org/dkade/BSD automates the HA jail from scratch, and the rest is just standard FreeBSD package management.

Disclaimer: I use AI as a productivity tool. For a senior engineer, AI is incredibly powerful as one can focus on the solution design and conceptualization and leave the boring part that is implementation to the AI.

Read more at -> https://aws.amazon.com/blogs/architecture/field-notes-how-olx-europe-fights-millions-of-bots-with-aws/