Skip to content

Build your personal knowledge base with Trilium Notes

feat(flatpak): vendor the manifest and write the packaging repo from it

Elian Doran7ea10f5f0e9f
diff --git a/apps/desktop/flatpak/org.triliumnotes.Trilium.yml b/apps/desktop/flatpak/org.triliumnotes.Trilium.yml
new file mode 100644
index 0000000000..d9ad780e6b
--- /dev/null
+++ b/apps/desktop/flatpak/org.triliumnotes.Trilium.yml
@@ -0,0 +1,94 @@
+app-id: org.triliumnotes.Trilium
+runtime: org.freedesktop.Platform
+runtime-version: '25.08'
+sdk: org.freedesktop.Sdk
+base: org.electronjs.Electron2.BaseApp
+base-version: '25.08'
+sdk-extensions:
+ # Provides node on PATH at build time only; nothing of it ships in the app.
+ - org.freedesktop.Sdk.Extension.node24
+command: trilium
+# Electron carries its own locale files
+separate-locales: false
+
+finish-args:
+ # Wayland first, X11 only where Wayland is unavailable.
+ - --socket=wayland
+ - --socket=fallback-x11
+ - --share=ipc
+ # GPU acceleration for the Chromium renderer.
+ - --device=dri
+ # Audio playback (attached media, notification sounds).
+ - --socket=pulseaudio
+ # Sync with self-hosted servers and fetching remote content in notes.
+ - --share=network
+ # Allow drag & drop from common dirs. Otherwise drag to import would fail due
+ # to unreachable files. See https://github.com/electron/electron/issues/30650
+ - --filesystem=xdg-download:ro
+ - --filesystem=xdg-documents:ro
+ - --filesystem=xdg-pictures:ro
+ - --filesystem=xdg-videos:ro
+ # Tray icon.
+ - --talk-name=org.kde.StatusNotifierWatcher
+
+modules:
+ - name: trilium
+ buildsystem: simple
+ build-options:
+ # pnpm first because apps/desktop/scripts/build.ts needs `pnpm build`.
+ append-path: /run/build/trilium/flatpak-node/pnpm:/usr/lib/sdk/node24/bin
+ env:
+ XDG_CACHE_HOME: /run/build/trilium/flatpak-node/cache
+ build-commands:
+ - pnpm install --offline --frozen-lockfile --reporter=append-only
+
+ - pnpm chore:update-build-info --from-commit
+ - pnpm desktop:build
+
+ - install -d /app/lib/trilium
+ - cp -a apps/desktop/dist/. /app/lib/trilium/
+
+ # Electron downloads its binary lazily on first use, which an offline sandbox cannot allow.
+ # Unpack the cached zip instead.
+ - unzip -q flatpak-node/cache/electron/electron-v*-linux-*.zip -d /app/lib/electron
+ - mv /app/lib/electron/electron /app/lib/electron/trilium
+ - rm /app/lib/electron/chrome-sandbox
+
+ - pnpm exec tsx apps/desktop/electron-forge/flip-fuses.ts /app/lib/electron/trilium
+ - pnpm exec tsx apps/desktop/electron-forge/trim-locales.ts /app/lib/electron/locales
+
+ - install -Dm755 trilium.sh /app/bin/trilium
+ - for s in 128 256 512; do install -Dm644 "apps/desktop/electron-forge/app-icon/png/${s}x${s}.png"
+ "/app/share/icons/hicolor/${s}x${s}/apps/${FLATPAK_ID}.png"; done
+ sources:
+ - type: git
+ url: https://github.com/TriliumNext/Trilium.git
+ tag: v0.105.0
+ commit: a0908a6e1e1741a3c3824d803da07300183dcb0c
+ - generated-sources.json
+ # pnpm 12 ships as a native binary per platform; the wrapper package's
+ # postinstall, which an offline sandbox cannot run, is what would pick one.
+ - type: archive
+ url: https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.4.2.tgz
+ sha256: 545b89d5c6026ac33d4c28bd3c6cc38cc050d571b35a4e69f13aad4a441af142
+ dest: flatpak-node/pnpm
+ only-arches: [x86_64]
+ - type: archive
+ url: https://registry.npmjs.org/@pnpm/exe.linux-arm64/-/exe.linux-arm64-12.4.2.tgz
+ sha256: c3bb8caba00f308733b0876d245e1e1f3ad656e6605f4f85dd861457267ae9f2
+ dest: flatpak-node/pnpm
+ only-arches: [aarch64]
+ - type: file
+ path: trilium.sh
+
+ # Separate module so a metadata edit does not invalidate app build.
+ - name: metadata
+ buildsystem: simple
+ build-commands:
+ - install -Dm644 ${FLATPAK_ID}.desktop /app/share/applications/${FLATPAK_ID}.desktop
+ - install -Dm644 ${FLATPAK_ID}.metainfo.xml /app/share/metainfo/${FLATPAK_ID}.metainfo.xml
+ sources:
+ - type: file
+ path: org.triliumnotes.Trilium.desktop
+ - type: file
+ path: org.triliumnotes.Trilium.metainfo.xml
diff --git a/apps/desktop/flatpak/trilium.sh b/apps/desktop/flatpak/trilium.sh
new file mode 100755
index 0000000000..4ef7d255ea
--- /dev/null
+++ b/apps/desktop/flatpak/trilium.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+
+# Use built-in directory, unless the user has already overridden or mounted their data directory.
+if [ -z "${TRILIUM_DATA_DIR:-}" ]; then
+ if [ ! -d "$XDG_DATA_HOME/trilium-data" ] && [ -d "$HOME/.local/share/trilium-data" ]; then
+ export TRILIUM_DATA_DIR="$HOME/.local/share/trilium-data"
+ else
+ export TRILIUM_DATA_DIR="$XDG_DATA_HOME/trilium-data"
+ fi
+fi
+
+exec zypak-wrapper /app/lib/electron/trilium /app/lib/trilium "$@"
diff --git a/scripts/generate-flatpak-sources.mts b/scripts/flatpak/generate-sources.mts
similarity index 97%
rename from scripts/generate-flatpak-sources.mts
rename to scripts/flatpak/generate-sources.mts
index 78427d8b69..70a66d31df 100644
--- a/scripts/generate-flatpak-sources.mts
+++ b/scripts/flatpak/generate-sources.mts
@@ -9,7 +9,7 @@
*
* Usage:
*
- * pnpm exec tsx ./scripts/generate-flatpak-sources.mts [output]
+ * pnpm exec tsx ./scripts/flatpak/generate-sources.mts [output]
*
* `output` is the file to write, or a directory to write `generated-sources.json`
* into — pass the packaging repo checkout to update its tracked copy in place.
@@ -23,7 +23,7 @@ import { execFileSync } from "node:child_process";
import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
import { dirname, join, relative, resolve } from "node:path";
-const ROOT = join(import.meta.dirname, "..");
+const ROOT = join(import.meta.dirname, "../..");
const PACKAGE_JSON_PATH = join(ROOT, "package.json");
const LOCKFILE_PATH = join(ROOT, "pnpm-lock.yaml");
diff --git a/scripts/generate-flatpak-sources.spec.ts b/scripts/flatpak/generate-sources.spec.ts
similarity index 99%
rename from scripts/generate-flatpak-sources.spec.ts
rename to scripts/flatpak/generate-sources.spec.ts
index 5e7653deba..5b6d8859db 100644
--- a/scripts/generate-flatpak-sources.spec.ts
+++ b/scripts/flatpak/generate-sources.spec.ts
@@ -4,7 +4,7 @@ import { join } from "node:path";
import { describe, expect, it } from "vitest";
-import { checkPnpm, filterSources, resolveOutputPath } from "./generate-flatpak-sources.mjs";
+import { checkPnpm, filterSources, resolveOutputPath } from "./generate-sources.mjs";
describe("checkPnpm", () => {
it("accepts the pinned pnpm major, with or without a corepack checksum", () => {
diff --git a/scripts/flatpak/update-repo.mts b/scripts/flatpak/update-repo.mts
new file mode 100644
index 0000000000..fc9ec60049
--- /dev/null
+++ b/scripts/flatpak/update-repo.mts
@@ -0,0 +1,134 @@
+/**
+ * Writes the Flathub packaging repo's files from their vendored sources in
+ * `apps/desktop/flatpak/`: the manifest — with its git source pinned to the
+ * requested ref and its pnpm sources tracking that ref's `packageManager` —
+ * plus the launch wrapper, desktop file and metainfo.
+ *
+ * Usage:
+ *
+ * pnpm exec tsx ./scripts/flatpak/update-repo.mts <packaging-repo-dir> [ref]
+ *
+ * `ref` defaults to HEAD; a tag pins `tag:` and `commit:`, anything else pins
+ * the bare commit (the beta case). `generated-sources.json` is a separate
+ * step: ./scripts/flatpak/generate-sources.mts, run against the same ref's
+ * checkout.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const FLATPAK_DIR = join(import.meta.dirname, "../../apps/desktop/flatpak");
+const MANIFEST_NAME = "org.triliumnotes.Trilium.yml";
+const COPIED_FILES = [
+ "trilium.sh",
+ "org.triliumnotes.Trilium.desktop",
+ "org.triliumnotes.Trilium.metainfo.xml"
+];
+
+export async function main(argv: string[]) {
+ const [repoDirArg, ref = "HEAD"] = argv;
+ if (!repoDirArg || !statSync(resolve(repoDirArg), { throwIfNoEntry: false })?.isDirectory()) {
+ throw new Error("Pass the packaging repo checkout to update.");
+ }
+ const repoDir = resolve(repoDirArg);
+
+ const commit = git("rev-parse", `${ref}^{commit}`);
+ const tag = isTag(ref) ? ref : undefined;
+
+ let manifest = updateGitSource(readFileSync(join(FLATPAK_DIR, MANIFEST_NAME), "utf-8"), commit, tag);
+
+ const pnpmVersion = parsePnpmVersion(git("show", `${commit}:package.json`));
+ if (getPnpmVersion(manifest) !== pnpmVersion) {
+ manifest = updatePnpmPins(manifest, pnpmVersion, {
+ x64: await sha256OfUrl(pnpmExeUrl("x64", pnpmVersion)),
+ arm64: await sha256OfUrl(pnpmExeUrl("arm64", pnpmVersion))
+ });
+ }
+
+ writeFileSync(join(repoDir, MANIFEST_NAME), manifest);
+ for (const file of COPIED_FILES) {
+ copyFileSync(join(FLATPAK_DIR, file), join(repoDir, file));
+ }
+ console.log(`Updated ${repoDir}: ${tag ?? "beta"} @ ${commit}, pnpm ${pnpmVersion}, `
+ + `${COPIED_FILES.length + 1} files.`);
+}
+
+/** Pins the manifest's git source; without a tag, the `tag:` line goes (a beta builds a bare commit). */
+export function updateGitSource(manifest: string, commit: string, tag?: string): string {
+ const gitSource = /(url: https:\/\/github\.com\/TriliumNext\/Trilium\.git\n)(\s*tag: \S+\n)?(\s*)commit: [0-9a-f]{40}/;
+ if (!gitSource.test(manifest)) {
+ throw new Error("Found no Trilium git source to pin in the manifest.");
+ }
+ return manifest.replace(gitSource, (_, urlLine: string, _tagLine: string, indent: string) =>
+ `${urlLine}${tag ? `${indent}tag: ${tag}\n` : ""}${indent}commit: ${commit}`);
+}
+
+/** The version the manifest's per-arch pnpm sources currently pin. */
+export function getPnpmVersion(manifest: string): string {
+ const url = /exe\.linux-x64-([\d.]+)\.tgz/.exec(manifest);
+ if (!url) {
+ throw new Error("Found no pnpm source in the manifest.");
+ }
+ return url[1];
+}
+
+export function parsePnpmVersion(packageJson: string): string {
+ const { packageManager } = JSON.parse(packageJson);
+ const version = /^pnpm@([\d.]+)/.exec(packageManager ?? "")?.[1];
+ if (!version) {
+ throw new Error(`Expected package.json to pin pnpm, got "${packageManager}".`);
+ }
+ return version;
+}
+
+export function updatePnpmPins(
+ manifest: string,
+ version: string,
+ hashes: { x64: string; arm64: string }
+): string {
+ let updated = manifest;
+ for (const arch of ["x64", "arm64"] as const) {
+ const source = new RegExp(
+ `(exe\\.linux-${arch}/-/exe\\.linux-${arch}-)[\\d.]+(\\.tgz\\n\\s*sha256: )[0-9a-f]{64}`);
+ if (!source.test(updated)) {
+ throw new Error(`Found no pnpm source for ${arch} in the manifest.`);
+ }
+ updated = updated.replace(source, `$1${version}$2${hashes[arch]}`);
+ }
+ return updated;
+}
+
+function pnpmExeUrl(arch: "x64" | "arm64", version: string): string {
+ return `https://registry.npmjs.org/@pnpm/exe.linux-${arch}/-/exe.linux-${arch}-${version}.tgz`;
+}
+
+async function sha256OfUrl(url: string): Promise<string> {
+ const response = await fetch(url);
+ if (!response.ok) {
+ throw new Error(`${response.status} fetching ${url}`);
+ }
+ return createHash("sha256").update(new Uint8Array(await response.arrayBuffer())).digest("hex");
+}
+
+function git(...args: string[]): string {
+ return execFileSync("git", args, { cwd: join(import.meta.dirname, "../..") }).toString().trim();
+}
+
+function isTag(ref: string): boolean {
+ try {
+ git("show-ref", "--verify", "--quiet", `refs/tags/${ref}`);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+// Only when run as a script — the pure helpers above are imported by the spec.
+if (process.argv[1] === import.meta.filename) {
+ main(process.argv.slice(2)).catch((err) => {
+ console.error(err instanceof Error ? err.message : err);
+ process.exit(1);
+ });
+}
diff --git a/scripts/flatpak/update-repo.spec.ts b/scripts/flatpak/update-repo.spec.ts
new file mode 100644
index 0000000000..c1ee3982f0
--- /dev/null
+++ b/scripts/flatpak/update-repo.spec.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { getPnpmVersion, parsePnpmVersion, updateGitSource, updatePnpmPins } from "./update-repo.mjs";
+
+const MANIFEST = `\
+modules:
+ - name: trilium
+ sources:
+ - type: git
+ url: https://github.com/TriliumNext/Trilium.git
+ tag: v0.105.0
+ commit: a0908a6e1e1741a3c3824d803da07300183dcb0c
+ - generated-sources.json
+ - type: archive
+ url: https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.4.2.tgz
+ sha256: 545b89d5c6026ac33d4c28bd3c6cc38cc050d571b35a4e69f13aad4a441af142
+ dest: flatpak-node/pnpm
+ only-arches: [x86_64]
+ - type: archive
+ url: https://registry.npmjs.org/@pnpm/exe.linux-arm64/-/exe.linux-arm64-12.4.2.tgz
+ sha256: c3bb8caba00f308733b0876d245e1e1f3ad656e6605f4f85dd861457267ae9f2
+ dest: flatpak-node/pnpm
+ only-arches: [aarch64]
+`;
+
+const NEW_COMMIT = "1234567890abcdef1234567890abcdef12345678";
+
+describe("updateGitSource", () => {
+ it("pins a release: tag and commit both move", () => {
+ const updated = updateGitSource(MANIFEST, NEW_COMMIT, "v0.106.0");
+ expect(updated).toContain(` tag: v0.106.0\n commit: ${NEW_COMMIT}`);
+ expect(updated).not.toContain("v0.105.0");
+ });
+
+ it("pins a beta: the tag line goes, only the commit stays", () => {
+ const updated = updateGitSource(MANIFEST, NEW_COMMIT);
+ expect(updated).toContain(`Trilium.git\n commit: ${NEW_COMMIT}`);
+ expect(updated).not.toContain("tag:");
+ });
+
+ it("re-adds a tag to a commit-only manifest", () => {
+ const beta = updateGitSource(MANIFEST, NEW_COMMIT);
+ const release = updateGitSource(beta, NEW_COMMIT, "v0.106.0");
+ expect(release).toContain(` tag: v0.106.0\n commit: ${NEW_COMMIT}`);
+ });
+
+ it("rejects a manifest without the git source", () => {
+ expect(() => updateGitSource("modules: []", NEW_COMMIT)).toThrow(/git source/);
+ });
+});
+
+describe("pnpm pins", () => {
+ it("reads the pinned version", () => {
+ expect(getPnpmVersion(MANIFEST)).toBe("12.4.2");
+ });
+
+ it("parses packageManager, with or without a corepack checksum", () => {
+ expect(parsePnpmVersion(`{ "packageManager": "[email protected]" }`)).toBe("12.5.0");
+ expect(parsePnpmVersion(`{ "packageManager": "[email protected]+sha512.abc" }`)).toBe("12.5.0");
+ expect(() => parsePnpmVersion(`{ "packageManager": "[email protected]" }`)).toThrow(/[email protected]/);
+ expect(() => parsePnpmVersion(`{}`)).toThrow(/undefined/);
+ });
+
+ it("moves both per-arch sources to the new version and hashes", () => {
+ const updated = updatePnpmPins(MANIFEST, "12.5.0", {
+ x64: "a".repeat(64),
+ arm64: "b".repeat(64)
+ });
+ expect(updated).toContain(`exe.linux-x64-12.5.0.tgz\n sha256: ${"a".repeat(64)}`);
+ expect(updated).toContain(`exe.linux-arm64-12.5.0.tgz\n sha256: ${"b".repeat(64)}`);
+ expect(updated).not.toContain("12.4.2");
+ });
+
+ it("rejects a manifest missing a per-arch source", () => {
+ const withoutArm = MANIFEST.replace("exe.linux-arm64", "exe.linux-mips");
+ expect(() => updatePnpmPins(withoutArm, "12.5.0", { x64: "a".repeat(64), arm64: "b".repeat(64) }))
+ .toThrow(/arm64/);
+ });
+});