How OpenChronology was built

#79 · Server .deb for Debian 13 and Ubuntu 24.04 (PostgreSQL and pgmp included)

2026-10-11T02:43:02Z CE

• timeline-app
• pull request
• packages

Fixes #72. ## The package `openchronology-server-debian13-amd64.deb` (PostgreSQL 17) and `openchronology-server-ubuntu24.04-amd64.deb` (PostgreSQL 16) are about 74 MB each. They contain: - the platform (Next.js standalone, editor, server modules) in `/usr/lib/openchronology`; - the **Node.js 24.21.0** runtime it's tested with, pinned by SHA-256; - `och-convert` and **`pgmp`** (the same pinned commit as `deploy/Dockerfile.postgres`), both compiled on the target distribution for its own libraries and PostgreSQL major version; - `openchronology-migrate`, systemd units for the server, mail delivery and the syslog receiver (the last two disabled), configuration templates, and docs including `README.Debian`. It depends on the distribution's PostgreSQL, so install with `sudo apt install ./openchronology-server-debian13-amd64.deb`. Plain `dpkg -i` works too, followed by `sudo apt -f install` for the dependencies. Internally the version is e.g. `0.1.0~dev.202610101535.eba5e34-1~deb13` for development builds. Releases use the tag, with pre-releases as `1.2.0~rc.1` so they sort before the release. ## First install (`postinst configure`) - Creates the `openchronology` system user. - Writes `/etc/openchronology/openchronology.env` (root:openchronology, 0640) from the template, with a fresh `AUTH_ENCRYPTION_KEY`, and `DATABASE_URL` pointed at the local cluster's socket and port. It also writes `syslog.env`. - Starts PostgreSQL if nothing has, for example in a container without systemd. - Creates the `openchronology` role and database, creates `pgmp` as the superuser (it isn't a trusted extension), runs `openchronology-migrate`, then enables and starts `openchronology.service`. The app's role never needs superuser rights. - If PostgreSQL can't be reached, it explains how to start it and finish with `dpkg-reconfigure`. Whether to set up a database depends on whether one exists, so a reconfigure after a failed first install still creates it. ## Upgrades - `prerm` stops the services. - `postinst` leaves the configuration and database untouched. It lists the settings in the new template that `/etc/openchronology/openchronology.env` lacks, gives the `diff -u` command to compare the two, and suggests a `pg_dump` backup. - It then says to run `sudo openchronology-migrate`, which migrates and starts the server. The configuration files are deliberately not dpkg conffiles: they're created once and then belong to the administrator, while each version's templates stay in `/usr/share/openchronology/`. **Removal:** `remove` stops and disables the services. `purge` also deletes `/etc/openchronology`. The database is never dropped; the purge message explains how to drop it. **Hardening:** the server unit runs as `openchronology` with `NoNewPrivileges`, `ProtectSystem=strict`, `PrivateTmp` and related settings. A small launcher (`openchronology-server.mjs`) maps the configuration's `HOST` to the `HOSTNAME` Next.js reads. Shells set `HOSTNAME` to the machine name, and `--env-file` never overrides it, which is how the first smoke test caught this. ## Build, CI and releases - **Build:** `node scripts/server-deb.mjs [debian13|ubuntu24.04]` builds with Docker into `server-artifacts/`. The build mirrors `deploy/Dockerfile.app`, including a web source archive with vendored Rust crates for the bundled `och-convert`. - **`.github/workflows/server-packages.yml`** (reusable): builds each target, runs `test/server-deb.mjs` on it, and uploads it. - **CI:** runs it on every push and pull request, so each push to `main` has both packages as artifacts (`server-debian13`, `server-ubuntu24.04`). - **Releases:** build from the tag, and `scripts/release-assets.mjs` now requires both packages before publishing. ## Tests - **`test/server-deb.mjs`** runs in a fresh container of the target distribution, without systemd: - the install path; - the role and database; - `pgmp` arithmetic (`'1/3'::mpq + '1/6'::mpq = 1/2`), the schema, and the configuration's permissions, generated key…

Open #79 · Server .deb for Debian 13 and Ubuntu 24.04 (PostgreSQL and pgmp included) in the timeline