How OpenChronology was built

#131 · Install the server on Windows with a self-contained installer

2026-10-13T13:25:09Z CE

• timeline-app
• pull request
• packages

Closes #116, the last of four PRs (RPM #119, FreeBSD #120, macOS #130): **Windows**, as a self-contained installer. ## The installer: `openchronology-server-windows-amd64-setup.exe` (~78 MB) It installs into `C:\Program Files\OpenChronology Server` everything the server needs, with nothing else required: | Part | Source | | --- | --- | | PostgreSQL 17.11 | EDB's Windows binaries, pinned by SHA-256, without pgAdmin, Stack Builder, docs, `.pdb` or `.lib` files | | pgmp | built with **MSVC** (`cl /LD`) against those PostgreSQL headers and `postgres.lib`, with GMP statically linked from vcpkg (as the desktop's Windows build has it). Scripts in `share\pgmp`, as its control file expects | | och-convert.exe | the desktop's Windows native build (`OCH_NATIVE_PREFIX`, static) | | Node.js 24.21.0 | the official `node.exe`, pinned | | WinSW 2.12.0 | MIT, pinned: runs the server as a Windows service | | The platform | `openchronology-server-platform.tar.gz` from #130 | `deploy/windows-server/build.ps1` builds it on `windows-2025` and creates it with NSIS (`installer.nsi`). ## Setup (`setup.ps1`, run elevated by the installer; Windows PowerShell 5.1 compatible) - **Configuration** in `C:\ProgramData\OpenChronology\openchronology.env`, readable only by Administrators, SYSTEM and the server's Local Service account. It holds a new `AUTH_ENCRYPTION_KEY` and `DATABASE_URL=postgresql://openchronology: @127.0.0.1:5442/openchronology`. - The superuser password is in `postgres-superuser.txt`, readable by Administrators and SYSTEM only. - Files are written without a byte-order mark, so PostgreSQL never reads one as part of a password. - **PostgreSQL** initialized in `ProgramData\OpenChronology\pgdata`, using SCRAM, UTF8 and the C locale. - It runs as **`OpenChronologyPostgreSQL`** (`pg_ctl register`, Network Service account, automatic start) on **127.0.0.1:5442** only, so it never clashes with another PostgreSQL. - `initdb` drops administrator rights (a restricted token), so its folder and password file belong to the installing account while it runs. Afterwards, access is narrowed to Administrators, SYSTEM and Network Service. - **Database:** the role, the database and `CREATE EXTENSION pgmp`, then the migration. - **Server:** the **`OpenChronology`** WinSW service, which: - runs `node.exe` on the launcher with `OCH_CONFIG` and `OCH_CONVERTER`; - runs as **Local Service**; - depends on the PostgreSQL service, with automatic delayed start and restart on failure; - writes rolling logs to `ProgramData\OpenChronology\logs`. - Setup waits for `/healthz`. If the server doesn't answer, it prints the service state and the logs. Its transcript goes to `ProgramData\OpenChronology\setup.log`. - **Upgrades** (a newer installer): - stop both services before replacing files; - keep the configuration and database; - **migrate automatically** and start again (what users expect of a Windows installer; the other packages ask for `openchronology-migrate`). - **Uninstall** (Apps, or `uninstall.exe /S`): stops and removes both services and the program, and **keeps** `ProgramData\OpenChronology` (the configuration and database). It's listed in Apps with its version. - **Silent install:** `setup.exe /S` exits with code **2** when setup doesn't finish. - **Commands** in the install folder, run as an administrator: `openchronology-migrate.cmd`, `openchronology-reset-admin-password.cmd` (#118), `och-import-logs.cmd`. Documented in `README.Windows.txt`. ## Fixes along the way (found by CI) - The shared **server launcher** imported `platform/server.cjs` by plain path, which Node refuses on Windows (`c:`). It now imports by file URL, and names `och-convert.exe` on Windows. Linux, FreeBSD and macOS are unaffected. - pgmp's SQL scripts belong in `share\pgmp` (the control file's `directory`). - PostgreSQL notices on stderr became fatal in Windows PowerShell 5.1. Setup now asks for warnings and above only, and judges `psql` by its exit code. - WinSW 2.12 has no `refresh` command. S…

Open #131 · Install the server on Windows with a self-contained installer in the timeline