How OpenChronology was built

#195 · The syslog receiver as a service on every server package (#125)

2026-10-17T14:36:36Z CE

• timeline-app
• pull request
• logs
• packages

Closes #125. The Debian and RPM packages already shipped a systemd unit for the syslog receiver (and the journald follower), and FreeBSD has an rc.d script. macOS and Windows had no service for it, and no package test ever ran one. This PR adds the missing services, so the receiver runs as a service on every system the server packages support. Each service is checked end to end in CI. ## The services | System | Service | Start it | | --- | --- | --- | | Debian, Ubuntu, Rocky, RHEL, Fedora | systemd unit (already there) | `sudo systemctl enable --now openchronology-syslog` | | FreeBSD | rc.d script (already there) | `sysrc openchronology_syslog_enable=YES && service openchronology_syslog start` | | **macOS** | **launchd agent (new)** | `openchronology-agent start syslog` | | **Windows** | **WinSW service (new)** | `Set-Service OpenChronologySyslog -StartupType Automatic; Start-Service OpenChronologySyslog` | | Docker Compose | `syslog` profile (already there) | `docker compose --profile syslog up -d syslog` | ### macOS: `openchronology-agent` - **Commands:** `openchronology-agent start|stop|restart|status syslog|mail`. - **What it does:** writes `~/Library/LaunchAgents/org.openchronology. .plist` and loads it in your login session. The worker starts now and at every login, and launchd restarts it if it stops. This is what `brew services` does for the server. - **Why a command:** a Homebrew formula can have only one `service`, and the server uses it. - **Stop:** unloads the agent, waits for the receiver to save its queue, and removes the plist, so it no longer starts at login. - **Status:** shows launchd's state, the process ID and the last exit code. - **Mail too:** email delivery had the same gap ("run it under your own launchd agent"), so the command covers `mail` as well. - **Templates:** the Homebrew configuration templates now say `openchronology-agent start …` where the Linux ones say `systemctl enable --now …`. ### Windows: `OpenChronologySyslog` and `OpenChronologyMail` - **Definitions:** two more WinSW services, alongside the server's. Each runs as Local Service and logs to `C:\ProgramData\OpenChronology\logs`. - **Installed stopped:** setup installs both set to start by hand, because each needs configuring first. That matches the Linux packages, where these units ship disabled. - **Configuration access:** setup makes `syslog.env` and a starter `syslog-routes.json` readable by Local Service. Files an administrator creates later in that folder would otherwise be readable by administrators only. An upgrade from before this PR fixes access on files that already exist. - **Upgrades:** the installer stops these services too. Setup then restarts the ones set to start with Windows. - **Uninstall:** removes both services. - **Docs:** `README.Windows.txt` and the templates give the PowerShell commands. Before this, Windows had no email delivery at all, and its template pointed at `systemctl`. ### The workers read their configuration `syslog-receiver.mjs` and `mail-worker.mjs` now load the file `OCH_CONFIG` names, as the journald follower already does, so a service only has to name the file. Under systemd nothing changes, because the unit passes the settings itself and leaves `OCH_CONFIG` unset. ### Docs `docs/syslog.md` has a new section, **Running it as a service**: per system, where the configuration is, how to start it and where it logs. It also says where to start from to run the receiver as a service from a checkout. ## Bugs the new checks found Running each service for real in CI found three bugs, now fixed: - **The receiver didn't start through a symlink.** It ran `main()` only when Node's script path was its own file. Homebrew's command names it through the formula's `opt` symlink, so under launchd it exited 0 at once, forever. It now compares real paths, as the journald follower and `och-import-logs` already did. - **FreeBSD's services held their starter's output open.** `daemon(8)` without `-f` kept the stdout of wha…

Open #195 · The syslog receiver as a service on every server package (#125) in the timeline