Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(desktop): add rpm target to the Linux build (#3101)

mike-inkeep3177889619a9
diff --git a/.changeset/linux-rpm-target.md b/.changeset/linux-rpm-target.md
new file mode 100644
index 000000000..7eeb5889e
--- /dev/null
+++ b/.changeset/linux-rpm-target.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+The Linux desktop build now also produces an `.rpm` package, so Fedora, RHEL, and other RPM-based distributions can install OpenKnowledge with their own package manager instead of unpacking a `.deb` by hand. The `.rpm` installs the same way the `.deb` does — it puts the app in the launcher, registers the `openknowledge://` links, and puts the `ok` command on your PATH — and it declares its system library requirements under their Fedora/RHEL names so the package manager pulls in anything missing. Both x86_64 and aarch64 packages are built.
diff --git a/.github/workflows/desktop-build-win-linux.yml b/.github/workflows/desktop-build-win-linux.yml
index 44d176eb5..c6399eeee 100644
--- a/.github/workflows/desktop-build-win-linux.yml
+++ b/.github/workflows/desktop-build-win-linux.yml
@@ -18,9 +18,10 @@ name: Desktop build (manual, Windows/Linux)
# the arch it targets.
#
# Artifacts are one-per-installer, each named for the file it holds
-# (OpenKnowledge-Setup-x64 / -arm64, OpenKnowledge-amd64-deb / -arm64-deb)
-# so an operator can grab just the one they're about to QA. GitHub zips
-# artifacts on download either way.
+# (OpenKnowledge-Setup-x64 / -arm64, OpenKnowledge-amd64-deb / -arm64-deb,
+# OpenKnowledge-x86_64-rpm / -aarch64-rpm) so an operator can grab just
+# the one they're about to QA. GitHub zips artifacts on download either
+# way.
#
# Windows signing (D3, Azure Artifact Signing): OPTIONAL here. When the
# three AZURE_* secrets + three AZURE_SIGNING_* repo variables are
@@ -313,10 +314,10 @@ jobs:
include:
- runner: ubuntu-latest
arch: x64
- targets: deb:x64
+ targets: deb:x64 rpm:x64
- runner: ubuntu-24.04-arm
arch: arm64
- targets: deb:arm64
+ targets: deb:arm64 rpm:arm64
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -371,10 +372,22 @@ jobs:
working-directory: packages/desktop
run: pnpm run build:desktop
+ # electron-builder downloads its own `fpm`, but fpm shells out to the
+ # host's `rpmbuild` to assemble an `.rpm` — and an Ubuntu runner has no
+ # rpm tooling preinstalled, so the rpm target dies with "Can't find
+ # rpmbuild". Ubuntu's `rpm` package carries /usr/bin/rpmbuild. The deb
+ # and AppImage targets need nothing extra, so this is the only apt step
+ # in the job.
+ - name: Install rpmbuild (fpm's rpm backend)
+ run: |
+ set -euo pipefail
+ sudo apt-get update
+ sudo apt-get install -y rpm
+
# Each cell packages only its own arch, on a runner of that arch — so the
- # `.deb` ships the matching `@parcel/watcher` / `@napi-rs/keyring`
- # prebuilds rather than degrading file-watching to chokidar. The deb
- # target needs `fpm`; electron-builder 26 downloads a native
+ # `.deb` / `.rpm` ship the matching `@parcel/watcher` / `@napi-rs/keyring`
+ # prebuilds rather than degrading file-watching to chokidar. The deb and
+ # rpm targets need `fpm`; electron-builder 26 downloads a native
# `linux-arm64v8` build of it (see app-builder-lib's `getFpmPath`), so no
# emulation or system fpm is involved.
- name: Package ${{ matrix.targets }}
diff --git a/packages/desktop/build/deb-postinst.sh b/packages/desktop/build/deb-postinst.sh
index 275977fd7..99acbc44b 100644
--- a/packages/desktop/build/deb-postinst.sh
+++ b/packages/desktop/build/deb-postinst.sh
@@ -1,10 +1,14 @@
#!/bin/bash
-# deb after-install script. electron-builder's FpmTarget passes custom
-# scripts through the SAME macro templating as its defaults — every
-# dollar-brace sequence is treated as a macro (unknown names throw at
-# build time, comments included), so bash variables here MUST use the
-# brace-less $NAME form.
+# after-install script, shared by the deb AND rpm targets (see the `rpm:` block
+# in electron-builder.yml for why one script serves both — every distro-
+# specific step below is already existence-guarded, so the Ubuntu-only halves
+# no-op on Fedora/RHEL rather than failing).
+#
+# electron-builder's FpmTarget passes custom scripts through the SAME macro
+# templating as its defaults — every dollar-brace sequence is treated as a
+# macro (unknown names throw at build time, comments included), so bash
+# variables here MUST use the brace-less $NAME form.
#
# The first half is a verbatim copy of app-builder-lib's
# templates/linux/after-install.tpl (a custom afterInstall REPLACES the
diff --git a/packages/desktop/build/deb-postrm.sh b/packages/desktop/build/deb-postrm.sh
index 5eaccd087..393f10103 100644
--- a/packages/desktop/build/deb-postrm.sh
+++ b/packages/desktop/build/deb-postrm.sh
@@ -1,11 +1,29 @@
#!/bin/bash
-# deb after-remove script. Verbatim copy of app-builder-lib's
+# after-remove script, shared by the deb AND rpm targets (see the `rpm:` block
+# in electron-builder.yml for why one script serves both). The body below the
+# guard is a verbatim copy of app-builder-lib's
# templates/linux/after-remove.tpl (a custom afterRemove REPLACES the
# default) + removal of the OpenKnowledge /usr/bin CLI symlinks that
# deb-postinst.sh created. Macro templating applies — bash variables must
# use the brace-less $NAME form (see deb-postinst.sh).
+# Upgrade guard — the one place the two packagers genuinely disagree, and the
+# reason this is not a verbatim copy. On rpm, the NEW package's %post runs
+# BEFORE the old package's %postun, so an unguarded teardown deletes the
+# symlinks and the update-alternatives entry that the upgrade just installed,
+# leaving `ok` off PATH until the next reinstall. dpkg orders it the other way
+# round, so the deb only ever benefited from the guard cosmetically (no window
+# where /usr/bin/ok is missing) — but it must not regress, hence one guard
+# that reads both dialects:
+# rpm %postun: $1 is the count of instances left after the operation —
+# 0 on a real erase, >=1 on an upgrade.
+# deb postrm : $1 is the action word — "remove"/"purge" on a real removal,
+# "upgrade"/"failed-upgrade"/"abort-upgrade" mid-upgrade.
+case "$1" in
+ upgrade | failed-upgrade | abort-upgrade | [1-9]*) exit 0 ;;
+esac
+
# Delete the link to the binary
if type update-alternatives >/dev/null 2>&1; then
update-alternatives --remove '${executable}' '/usr/bin/${executable}'
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index 3d8fb38c4..2a7a7b7b3 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -483,6 +483,17 @@ linux:
target:
- target: deb
arch: [x64, arm64]
+ # rpm for the Fedora/RHEL family, same integration grade as the deb (both
+ # go through electron-builder's FpmTarget and share the maintainer
+ # scripts). Built on the same native runners as the debs, for the same
+ # prebuilt-natives reason.
+ - target: rpm
+ arch: [x64, arm64]
+ # Per-target arch naming is electron-builder's, not ours: this one pattern
+ # yields OpenKnowledge-amd64.deb / OpenKnowledge-arm64.deb and
+ # OpenKnowledge-x86_64.rpm / OpenKnowledge-aarch64.rpm (`getArtifactArchName`
+ # in builder-util rewrites `${arch}` per extension). deb and rpm therefore
+ # never collide on a filename even where the arch word differs.
artifactName: ${productName}-${arch}.${ext}
# Terminal dock dark off-mac — keep node-pty out, and keep native-config's
# darwin cargo `target/` tree out (see win.files for the rationale).
@@ -535,6 +546,57 @@ deb:
- libcups2
- libgbm1
+rpm:
+ # Same maintainer scripts as the deb, deliberately. Every distro-specific
+ # step in them is already existence-guarded, so they no-op rather than fail
+ # on a Fedora/RHEL host: `update-alternatives` is present (chkconfig),
+ # `update-mime-database` / `update-desktop-database` sit behind `hash`, and
+ # the AppArmor block behind `apparmor_status --enabled`, which is simply
+ # absent outside the Ubuntu family. There are no dpkg-isms. The one thing
+ # they did NOT handle is rpm's upgrade ordering — the removal script grew a
+ # guard for it; see the header of build/deb-postrm.sh.
+ afterInstall: build/deb-postinst.sh
+ afterRemove: build/deb-postrm.sh
+ # Our own list, not electron-builder's rpm default. The first eight entries
+ # are the Fedora/RHEL names for the `deb.depends` list above, in the same
+ # order. The default drops libsecret (the keyring backend), so an rpm built
+ # on it would install cleanly and then silently downgrade auth to the
+ # plaintext file store.
+ #
+ # `libxss1` has NO rpm counterpart here, deliberately. Its Fedora name is
+ # libXScrnSaver, which is EPEL-only on RHEL 10 — requiring it would make the
+ # package uninstallable on a stock RHEL 10 box. It buys nothing in exchange:
+ # `objdump -p` on the packaged `openknowledge` binary lists 34 DT_NEEDED
+ # entries and none of them is libXss (Electron moved idle detection to
+ # DBus). The deb keeps its `libxss1` because that is electron-builder's
+ # stock set and it is a harmless no-op on Debian/Ubuntu, where the package
+ # is in the default repos.
+ #
+ # The last three ARE direct DT_NEEDED entries of that same binary; without
+ # them the app dies at exec with a bare dynamic-linker error and no
+ # user-visible signal. They are absent from the deb list above only because
+ # that gap is being closed separately — the two lists are meant to stay a
+ # mirror of each other, which
+ # tests/unit/electron-builder-linux-depends-parity.test.ts enforces.
+ #
+ # Upstream spells two of its defaults as rpm boolean deps —
+ # `(libXtst or libXtst6)`, `(libuuid or libuuid1)` — to also satisfy
+ # openSUSE's soname-style naming. We use the plain Fedora/RHEL names:
+ # openSUSE is not a target, and a half-boolean list would imply coverage we
+ # do not test.
+ depends:
+ - gtk3
+ - libnotify
+ - nss
+ - libXtst
+ - xdg-utils
+ - at-spi2-core
+ - libuuid
+ - libsecret
+ - alsa-lib
+ - cups-libs
+ - mesa-libgbm
+
# Flip fuses (D17 LOCKED, spec §8.9) on the packed app before code signing —
# all platforms (D9): off-darwin builds without the fuse flip would ship
# without RunAsNode, silently breaking the bundled-CLI/detached-spawn path.
diff --git a/packages/desktop/tests/unit/electron-builder-linux-depends-parity.test.ts b/packages/desktop/tests/unit/electron-builder-linux-depends-parity.test.ts
new file mode 100644
index 000000000..1e493797f
--- /dev/null
+++ b/packages/desktop/tests/unit/electron-builder-linux-depends-parity.test.ts
@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+import { parse } from 'yaml';
+
+/**
+ * Drift guard: `deb.depends` and `rpm.depends` in electron-builder.yml declare
+ * the SAME runtime set under two distros' naming schemes. Nothing but prose
+ * held them together before this test, and the two lists fail in opposite
+ * directions when they drift — a missing deb entry surfaces at `apt install`,
+ * a missing rpm entry surfaces as the app exiting at exec with a bare
+ * dynamic-linker message and no window, dialog, or log.
+ *
+ * The translation below is the contract. Adding a dependency to either list
+ * without teaching the table about it fails here rather than in a user's
+ * package manager.
+ */
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const desktopRoot = resolve(__dirname, '../..');
+const builderYml = resolve(desktopRoot, 'electron-builder.yml');
+
+/**
+ * Debian package name → its Fedora/RHEL counterpart, or `null` for the
+ * deliberate non-translations.
+ *
+ * `libxss1` is the only `null` today. Its Fedora name, libXScrnSaver, is
+ * EPEL-only on RHEL 10, so requiring it would make the rpm uninstallable on a
+ * stock box — and it buys nothing: `objdump -p` on the packaged
+ * `openknowledge` binary lists 34 DT_NEEDED entries and libXss is not among
+ * them (Electron moved idle detection to DBus). The deb keeps its entry
+ * because that list is electron-builder's stock set and the package is in
+ * Debian/Ubuntu's default repos, where an unused dependency is a no-op.
+ */
+const DEB_TO_RPM: Record<string, string | null> = {
+ 'libgtk-3-0': 'gtk3',
+ libnotify4: 'libnotify',
+ libnss3: 'nss',
+ libxss1: null,
+ libxtst6: 'libXtst',
+ 'xdg-utils': 'xdg-utils',
+ 'libatspi2.0-0': 'at-spi2-core',
+ libuuid1: 'libuuid',
+ 'libsecret-1-0': 'libsecret',
+ // Direct DT_NEEDED entries of the packaged binary. The rpm list carries
+ // these unconditionally (see RPM_DT_NEEDED_ADDITIONS); the deb list is
+ // gaining them separately, and this table keeps the union stable either way.
+ libasound2: 'alsa-lib',
+ libcups2: 'cups-libs',
+ libgbm1: 'mesa-libgbm',
+};
+
+/**
+ * rpm entries that must be present whether or not the deb list has caught up.
+ * The Electron binary lists all three as direct DT_NEEDED entries, so a
+ * package missing any of them installs cleanly and then cannot start.
+ */
+const RPM_DT_NEEDED_ADDITIONS = ['alsa-lib', 'cups-libs', 'mesa-libgbm'];
+
+function readDepends(): { deb: string[]; rpm: string[] } {
+ const config = parse(readFileSync(builderYml, 'utf8')) as {
+ deb?: { depends?: unknown };
+ rpm?: { depends?: unknown };
+ };
+ const deb = config.deb?.depends;
+ const rpm = config.rpm?.depends;
+ if (!Array.isArray(deb) || !Array.isArray(rpm)) {
+ throw new Error(
+ 'electron-builder.yml must declare both deb.depends and rpm.depends as arrays — ' +
+ 'a `depends` key that is absent hands the target back to electron-builder’s stock ' +
+ 'list, which omits libsecret on rpm and all three DT_NEEDED libraries on both.',
+ );
+ }
+ return { deb: deb as string[], rpm: rpm as string[] };
+}
+
+describe('deb.depends and rpm.depends declare the same runtime set', () => {
+ test('neither list repeats an entry', () => {
+ const { deb, rpm } = readDepends();
+ expect(new Set(deb).size, `deb.depends has a duplicate: ${deb.join(', ')}`).toBe(deb.length);
+ expect(new Set(rpm).size, `rpm.depends has a duplicate: ${rpm.join(', ')}`).toBe(rpm.length);
+ });
+
+ test('every deb dependency has a declared rpm translation', () => {
+ const { deb } = readDepends();
+ const untranslated = deb.filter((name) => !(name in DEB_TO_RPM));
+ expect(
+ untranslated,
+ `deb.depends gained ${untranslated.join(', ')} with no entry in this test's DEB_TO_RPM ` +
+ 'table. Add the Fedora/RHEL name (or an explicit null plus the reason it does not ' +
+ 'translate) here AND to rpm.depends in electron-builder.yml.',
+ ).toEqual([]);
+ });
+
+ test('every rpm dependency is either a translated deb entry or a known DT_NEEDED addition', () => {
+ const { rpm } = readDepends();
+ const known = new Set([
+ ...Object.values(DEB_TO_RPM).filter((v): v is string => v !== null),
+ ...RPM_DT_NEEDED_ADDITIONS,
+ ]);
+ const unexplained = rpm.filter((name) => !known.has(name));
+ expect(
+ unexplained,
+ `rpm.depends carries ${unexplained.join(', ')}, which maps back to nothing. Either add ` +
+ 'the matching deb dependency and its DEB_TO_RPM entry, or — if it is genuinely ' +
+ 'rpm-only — list it in RPM_DT_NEEDED_ADDITIONS with the reason.',
+ ).toEqual([]);
+ });
+
+ test('rpm.depends is exactly the translated deb set plus the DT_NEEDED additions', () => {
+ const { deb, rpm } = readDepends();
+ // Set semantics, not positional: the point is that neither list can gain
+ // or lose a library without the other moving. Once the deb list picks up
+ // libasound2 / libcups2 / libgbm1 they translate onto the same three names
+ // the additions already contribute, so this expectation holds unchanged
+ // across that landing — it does not need a revision then.
+ const expected = new Set([
+ ...deb.map((name) => DEB_TO_RPM[name]).filter((v): v is string => v != null),
+ ...RPM_DT_NEEDED_ADDITIONS,
+ ]);
+ expect(
+ [...rpm].sort(),
+ 'rpm.depends and deb.depends have drifted. Both lists in electron-builder.yml describe ' +
+ 'one runtime set; change them together.',
+ ).toEqual([...expected].sort());
+ });
+
+ test('rpm.depends does not require libXScrnSaver', () => {
+ // Regression pin, not a restatement of the table above: requiring it makes
+ // the package uninstallable on a stock RHEL 10 (EPEL-only there), and the
+ // packaged binary has no libXss DT_NEEDED entry to justify the cost. A
+ // future editor "restoring parity" with libxss1 would reintroduce that.
+ const { rpm } = readDepends();
+ expect(rpm).not.toContain('libXScrnSaver');
+ });
+
+ test('rpm reuses the deb maintainer scripts', () => {
+ // The scripts are shared on purpose (every distro-specific step in them is
+ // existence-guarded). Pointing rpm at its own copy would fork the
+ // /usr/bin/ok symlink behaviour and the upgrade guard silently.
+ const config = parse(readFileSync(builderYml, 'utf8')) as {
+ deb?: { afterInstall?: unknown; afterRemove?: unknown };
+ rpm?: { afterInstall?: unknown; afterRemove?: unknown };
+ };
+ expect(config.rpm?.afterInstall).toBe(config.deb?.afterInstall);
+ expect(config.rpm?.afterRemove).toBe(config.deb?.afterRemove);
+ });
+});