How OpenChronology was built

#120 · Build the server as FreeBSD packages

2026-10-13T03:22:41Z CE

• timeline-app
• pull request
• packages

Part of #116, the second of four PRs: **FreeBSD 14 and 15** (after RPM in #119; macOS and Windows follow). ## Packages | Target | PostgreSQL | Node.js | Asset | | --- | --- | --- | --- | | FreeBSD 14 (newest 14.x) | 17 (`postgresql17-server`) | FreeBSD's `node24` | `openchronology-server-freebsd14-amd64.pkg` | | FreeBSD 15 (newest 15.x) | 17 | `node24` | `openchronology-server-freebsd15-amd64.pkg` | Packages are tied to a FreeBSD major version, hence one per release. ## How it's built 1. **On Linux** (`deploy/freebsd-server/Dockerfile`, via `scripts/server-package.mjs freebsd14|15`): the same platform build as the other packages. - It drops the Linux-only `@img/sharp` binaries (the platform doesn't optimize images) and bundles no Node runtime. - It writes `server-artifacts/freebsd/` (the app tarball plus `build.env`: version, PostgreSQL major, asset name). 2. **On FreeBSD** (`deploy/freebsd-server/build.sh`, as root): installs the build tools and runtime dependencies, then builds `och-convert` and pinned pgmp against FreeBSD's GMP, SQLite and PostgreSQL. It lays the server out under `/usr/local` and runs `pkg create`. - The manifest depends on `node24`, `postgresql17-server`, `postgresql17-client`, `gmp` and `sqlite3`. - The package version comes from the release tag (dev builds become `0.1.0.dev. . `). 3. **CI** (`server-packages.yml`): - `Server / freebsd14|15`: builds the platform on Ubuntu, then the package in a FreeBSD VM (`vmactions/freebsd-vm`, pinned to v1.5.7) and uploads it. - `Server / freebsd14|15 install`: installs it on a **fresh** FreeBSD VM with exactly the documented command, then runs `test/server-freebsd.mjs` there. ## Installation As root: `fetch …/openchronology-server-freebsd15-amd64.pkg && pkg install -y ./openchronology-server-freebsd15-amd64.pkg && openchronology-setup` - `pkg install` of the local file fetches the dependencies from FreeBSD's repositories (verified on CI). - **The package starts nothing itself.** pkg kills whatever a package's scripts leave running, which is why FreeBSD's ports don't start services. CI showed the PostgreSQL and server our script had started being killed the moment `pkg install` returned. - So a first install prints "To finish, as root: openchronology-setup". `openchronology-setup`, mirroring the RPM's: - initializes PostgreSQL 17 (`/var/db/postgres/data17`, peer auth, UTF8) and enables and starts it; - writes `/usr/local/etc/openchronology/openchronology.env` with a new `AUTH_ENCRYPTION_KEY` and `DATABASE_URL=postgresql://openchronology@/openchronology?host=/tmp`. The user is named because FreeBSD's `su -m` keeps `USER=root`, which the PostgreSQL client would otherwise connect as. CI caught this. - creates the role, the database and pgmp, migrates, and runs `sysrc openchronology_enable=YES` and `service openchronology start`. - **Upgrades** (`pkg install` of a newer package) stop the services and print the same advice as the Linux packages, without starting anything. - **Removal** keeps the configuration and database and prints how to delete them, including the `sysrc -x` lines. ## Services and commands - **rc.d services** `openchronology`, `openchronology_mail` and `openchronology_syslog` run under `daemon(8)`: as the `openchronology` user, restarted on failure, logging to syslog. - **Configuration** is read with #121's parser (`OCH_CONFIG`), never Node's `--env-file`: - the server and the commands load it themselves; - the mail and syslog workers load it through `server/load-configuration.mjs` (`node --import`). - **Commands:** `openchronology-migrate` and `openchronology-reset-admin-password` (from #121), using `su -m`; `och-import-logs`. - Docs: `README.FreeBSD`, the README's package table, `docs/administration.md`, and download-page cards for FreeBSD 15 and 14 (FreeBSD browsers are recognized). ## Tests (CI, fresh FreeBSD 14 and 15 VMs; both pass) `test/server-freebsd.mjs` checks: - `pkg install` leaves PostgreSQL stopped; - `openchronology-setup`: PostgreSQL ena…

Open #120 · Build the server as FreeBSD packages in the timeline