How OpenChronology was built

#130 · Install the server on macOS with Homebrew

2026-10-13T04:54:14Z CE

• timeline-app
• pull request
• packages

Part of #116, the third of four PRs: **macOS through Homebrew** (after RPM #119 and FreeBSD #120; Windows follows). ## Installing ```sh brew install openchronology/tap/openchronology-server openchronology-setup ``` ## The formula (`deploy/homebrew/openchronology-server.rb.in`) - Its source is the release asset **`openchronology-server-platform.tar.gz`** (see below), with its SHA-256. - **Dependencies:** `node@24`, `postgresql@17`, `gmp` and `sqlite`. Build-only: `rust`, `cmake`, `pkgconf`, and macOS's own Python. - **Build:** - `och-convert` builds with `cargo --offline` from the crates vendored in the archive. - pgmp (pinned commit, as a `resource`) builds against `postgresql@17` and installs into the formula's own `lib/postgresql@17` and `share/postgresql@17`, as `pgvector` does. - The platform goes into `libexec`. - **Commands** in `bin`, with this installation's paths filled in: `openchronology-setup`, `openchronology-migrate`, `openchronology-reset-admin-password` (#118), `och-import-logs`, `openchronology-mail` and `openchronology-syslog` (the last two run in the foreground). - **`service`:** `brew services start openchronology-server` runs `node@24` on the launcher with `OCH_CONFIG`, logs to `var/log/openchronology.log`, and keeps it alive. - **`test`:** runs `och-import-logs --help`, and loads pgmp in a scratch PostgreSQL 17 cluster (`'1/3'::mpq + '1/6'::mpq = 1/2`). - **Caveats** say to run `openchronology-setup`, and `openchronology-migrate` after upgrades. ## `openchronology-setup`, as you Homebrew's PostgreSQL runs as the user, so the server does too, with no root and no system user. - Starts `postgresql@17` with `brew services` if needed. - **Refuses another PostgreSQL major version** on the same socket, and says how to switch: pgmp is built for 17, and GitHub's runners, like many Macs, may run an older one. - Writes `etc/openchronology/openchronology.env` (mode 600) with a new key and `DATABASE_URL=postgresql:// @/openchronology?host=/tmp`. - Runs `createdb` and `CREATE EXTENSION pgmp`, migrates, and starts the service. - Run again, it keeps everything and gives the upgrade advice. ## One platform archive for FreeBSD and Homebrew FreeBSD's Linux-built bundle becomes `deploy/platform/Dockerfile`, which produces **`openchronology-server-platform.tar.gz`**. It contains: - the platform; - docs; - `native/`: `native-store`, `sqlite-rational`, the vendored Rust crates and a `.cargo/config.toml` for offline builds; - `homebrew/`: the commands and configuration templates. CI builds it once (`Server / platform`), and both the FreeBSD jobs and the macOS job use it. The release workflow attaches it, and release validation requires it. ## Releases → the tap A new `homebrew` job runs after `publish`, for **stable releases only**: - downloads the release's platform archive; - renders the formula with its release URL and SHA-256 (`scripts/homebrew-formula.mjs`, which also hashes the pgmp tarball); - pushes `Formula/openchronology-server.rb` and a README to `openchronology/homebrew-tap` with the `HOMEBREW_TAP_DEPLOY_KEY` secret. The tap stays empty until the first stable release. ## CI (`Server / macos`, macos-15, passes) 1. Renders the formula for the CI archive (`file://` URL) into a local tap. 2. Stops any PostgreSQL the runner runs. 3. `brew install --build-from-source` as users would, then `brew test`. 4. Runs `test/server-homebrew.mjs`, which checks: - setup: pgmp, the schema, mode 600, the key and `DATABASE_URL`; - `brew services` started, and `/healthz`, `/api/session`, `/api/plugins` and `/` answering; - `och-import-logs`; - the admin password containing `#`, then the reset command (#118); - setup again keeping the key; - `brew uninstall` keeping the configuration and data. **Found by CI:** Homebrew's automatic cleanup removes `postgresql@17` when the server is uninstalled, since it's no longer needed. The databases stay on disk, but PostgreSQL goes. `README.Homebrew` now explains how to keep it (`brew install postgres…

Open #130 · Install the server on macOS with Homebrew in the timeline