Skip to content

Build your personal knowledge base with Trilium Notes

build(flatpak): build and run the Flathub recipe locally

Elian Doran19e9ed49d33b
diff --git a/.claude/skills/packaging-for-flathub/SKILL.md b/.claude/skills/packaging-for-flathub/SKILL.md
index 28d98821ff..9b15535825 100644
--- a/.claude/skills/packaging-for-flathub/SKILL.md
+++ b/.claude/skills/packaging-for-flathub/SKILL.md
@@ -55,6 +55,31 @@ pnpm exec tsx scripts/flatpak/generate-sources.mts ../org.triliumnotes.Trilium
commit. The pinned commit must be **pushed** — Flathub clones `TriliumNext/Trilium` at
that SHA.
+To build and run the Flathub recipe locally, without touching the packaging repo:
+
+```sh
+pnpm desktop:flathub-build # scripts/flatpak/build-local.mts
+pnpm desktop:flathub-start
+```
+
+`build-local.mts` renders the same manifest into `apps/desktop/out/flathub/` with the git
+source swapped for a `type: dir` source over the working tree, so uncommitted changes are
+built and nothing needs committing or pushing. `skip` matches exact relative paths, not
+patterns, so the script lists every path `git ls-files --others --ignored --directory`
+reports (~200: each `node_modules`, `dist`, …). `.git` stays in: the manifest's
+`chore:update-build-info --from-commit` reads `git log`, and the local build keeps
+Flathub's build commands unchanged. It regenerates `generated-sources.json` only when the
+working tree's lockfile changes, and installs through `org.flatpak.Builder` as branch `local`, beside the Flathub install. An
+install becomes flatpak's `current` branch, which the desktop launcher runs, so the script
+puts the previous one back (`flatpak info` cannot report it once several are installed;
+the script reads the `app/<id>/current` link).
+`flathub:start` runs that branch on its own `trilium-data-local` and Electron data dirs
+under `~/.var/app/org.triliumnotes.Trilium`, so a dev build never migrates the real
+sandboxed database. Without `flatpak-node-generator` on PATH it runs the generator on the
+Builder's Python from `~/.cache/flatpak-builder-tools` (cloned at the CI pin), raising
+aiohttp 3.10's 8190-byte header limit, which GitHub's release responses exceed. A full
+build takes about ten minutes.
+
## Settled decisions and why (do not relitigate without new facts)
- **From source, not repackaged.** The AppImage-extract fallback (Zettlr-style) exists
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 4cd6dc2b7d..2da0b2514b 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -21,6 +21,8 @@
"electron-forge:package": "pnpm build && electron-forge package dist",
"electron-forge:test-packaged": "pnpm electron-forge:package && tsx scripts/test-packaged.ts",
"electron-forge:start":"pnpm build && electron-forge start dist",
+ "flathub:build": "tsx ../../scripts/flatpak/build-local.mts",
+ "flathub:start": "flatpak run --branch=local --env=TRILIUM_DATA_DIR=$HOME/.var/app/org.triliumnotes.Trilium/data/trilium-data-local --env=TRILIUM_ELECTRON_DATA_DIR=$HOME/.var/app/org.triliumnotes.Trilium/config/trilium-electron-local org.triliumnotes.Trilium",
"e2e": "pnpm build && cross-env TRILIUM_INTEGRATION_TEST=memory-no-store TRILIUM_PORT=8082 TRILIUM_DATA_DIR=data-e2e TRILIUM_ELECTRON_DATA_DIR=data-e2e-electron-8082 ELECTRON_IS_DEV=0 playwright test",
"generate-setup-banners": "tsx electron-forge/setup-icon/generate/generate.mts",
"generate-dmg-background": "tsx electron-forge/dmg-background/generate.mts",
diff --git a/package.json b/package.json
index 0c77f61af0..574d692eac 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,8 @@
"desktop:start": "pnpm run --filter desktop dev",
"desktop:build": "pnpm run --filter desktop build",
"desktop:start-prod": "pnpm run --filter desktop start-prod",
+ "desktop:flathub-build": "pnpm run --filter desktop flathub:build",
+ "desktop:flathub-start": "pnpm run --filter desktop flathub:start",
"standalone:start": "pnpm run --filter standalone dev",
"standalone:build": "pnpm run --filter standalone build",
"standalone:test": "pnpm run --filter standalone test",
diff --git a/scripts/flatpak/build-local.mts b/scripts/flatpak/build-local.mts
new file mode 100644
index 0000000000..23b9a8aed3
--- /dev/null
+++ b/scripts/flatpak/build-local.mts
@@ -0,0 +1,182 @@
+/**
+ * Builds the Flathub flatpak from this checkout's working tree and installs it for the
+ * current user as the `local` branch of org.triliumnotes.Trilium, next to any install
+ * from Flathub.
+ *
+ * The manifest is the one ./scripts/flatpak/update-repo.mts writes for Flathub, except
+ * that its git source becomes a `dir` source over this checkout: the build sees the files
+ * on disk, uncommitted changes included, minus everything git ignores. `.git` stays in,
+ * because the manifest stamps the build info from `git log`.
+ * `generated-sources.json` is regenerated only when the lockfile changes.
+ *
+ * Usage:
+ *
+ * pnpm exec tsx ./scripts/flatpak/build-local.mts
+ *
+ * Then run it with `flatpak run --branch=local org.triliumnotes.Trilium`.
+ *
+ * Builds through the org.flatpak.Builder flatpak. Without `flatpak-node-generator` on
+ * PATH, the generator runs on that flatpak's Python from a flatpak-builder-tools
+ * checkout under ~/.cache, cloned on first use.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+import { main as generateSources } from "./generate-sources.mjs";
+import { MANIFEST_NAME, renderManifest, writePackagingFiles } from "./update-repo.mjs";
+
+const REPO_ROOT = resolve(import.meta.dirname, "../..");
+const OUT_DIR = join(REPO_ROOT, "apps/desktop/out/flathub");
+const SOURCES_LOCKFILE_STAMP = join(OUT_DIR, "generated-sources.lockfile");
+const APP_ID = "org.triliumnotes.Trilium";
+const LOCAL_BRANCH = "local";
+// Must match the commit .github/workflows/release-flathub.yml installs.
+const GENERATOR_COMMIT = "41c20aa10819cdb2a4f3ca171758a96d1955c018";
+const GENERATOR_REPO = "https://github.com/flatpak/flatpak-builder-tools.git";
+
+export async function main() {
+ mkdirSync(OUT_DIR, { recursive: true });
+
+ const { manifest } = await renderManifest("HEAD");
+ const ignored = parseIgnoredPaths(
+ git("ls-files", "--others", "--ignored", "--exclude-standard", "--directory")
+ );
+ writePackagingFiles(OUT_DIR, useLocalDirSource(manifest, REPO_ROOT, ignored));
+ updateSources();
+
+ const currentBranch = getCurrentBranch();
+ // A Nix shell sets SOURCE_DATE_EPOCH to 1980, which would date the export, and flatpak
+ // refuses to install a commit older than the installed one.
+ const { SOURCE_DATE_EPOCH: _, ...env } = process.env;
+ execFileSync("flatpak", [
+ "run", "org.flatpak.Builder",
+ "--user", "--install", "--force-clean",
+ "--install-deps-from=flathub",
+ `--default-branch=${LOCAL_BRANCH}`,
+ "builddir", MANIFEST_NAME
+ ], { cwd: OUT_DIR, env, stdio: "inherit" });
+ // An install becomes the default branch, which the desktop launcher runs on the real data.
+ if (currentBranch && currentBranch !== LOCAL_BRANCH) {
+ execFileSync("flatpak", [ "make-current", "--user", APP_ID, currentBranch ], {
+ stdio: "inherit"
+ });
+ }
+ console.log(`Installed the working tree as the "${LOCAL_BRANCH}" branch.`);
+}
+
+/**
+ * The branch `flatpak run` picks without `--branch`, if the app is installed. `flatpak info`
+ * cannot tell: it refuses to pick one once several branches are installed.
+ */
+function getCurrentBranch(): string | undefined {
+ const userDir = process.env.FLATPAK_USER_DIR ?? join(dataDir(), "flatpak");
+ try {
+ return basename(readlinkSync(join(userDir, "app", APP_ID, "current")));
+ } catch {
+ return undefined;
+ }
+}
+
+/**
+ * Replaces the manifest's Trilium git source with a `dir` source over a local checkout.
+ * flatpak-builder matches `skip` entries as exact relative paths, not patterns, so each
+ * ignored path is listed on its own.
+ */
+export function useLocalDirSource(manifest: string, repoDir: string, skip: string[]): string {
+ const gitSource = new RegExp("^([ \\t]*)- type: git\\n"
+ + "[ \\t]*url: https://github\\.com/TriliumNext/Trilium\\.git\\n"
+ + "(?:[ \\t]*tag: .*\\n)?"
+ + "[ \\t]*commit: .*\\n", "m");
+ if (!gitSource.test(manifest)) {
+ throw new Error("Found no Trilium git source to replace with the local checkout.");
+ }
+ return manifest.replace(gitSource, (_, indent: string) => [
+ `${indent}- type: dir`,
+ `${indent} path: ${JSON.stringify(repoDir)}`,
+ `${indent} skip:`,
+ ...skip.map((path) => `${indent} - ${JSON.stringify(path)}`),
+ ""
+ ].join("\n"));
+}
+
+/** The `git ls-files --ignored --directory` output as paths, without those inside another. */
+export function parseIgnoredPaths(lsFilesOutput: string): string[] {
+ const paths = lsFilesOutput.split("\n")
+ .map((line) => line.trim().replace(/\/$/, ""))
+ .filter(Boolean);
+ return paths.filter((path) => !paths.some((other) => path.startsWith(`${other}/`)));
+}
+
+/** Regenerates the sources from the working tree's lockfile, unless it is unchanged. */
+function updateSources() {
+ const lockfileHash = createHash("sha256")
+ .update(readFileSync(join(REPO_ROOT, "pnpm-lock.yaml")))
+ .digest("hex");
+ const sourcesPath = join(OUT_DIR, "generated-sources.json");
+ if (existsSync(sourcesPath) && readStamp() === lockfileHash) {
+ console.log("The lockfile is unchanged; reusing generated-sources.json.");
+ return;
+ }
+ generateSources([ OUT_DIR ], generatorCommand());
+ writeFileSync(SOURCES_LOCKFILE_STAMP, lockfileHash);
+}
+
+function readStamp() {
+ return existsSync(SOURCES_LOCKFILE_STAMP)
+ ? readFileSync(SOURCES_LOCKFILE_STAMP, "utf-8")
+ : undefined;
+}
+
+function generatorCommand(): string[] {
+ try {
+ execFileSync("flatpak-node-generator", [ "--help" ], { stdio: "ignore" });
+ return [ "flatpak-node-generator" ];
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+ throw err;
+ }
+ }
+
+ // org.flatpak.Builder sees the host's home directory but not its /tmp.
+ const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+ const checkout = join(cacheDir, "flatpak-builder-tools");
+ if (!existsSync(checkout)) {
+ execFileSync("git", [ "clone", "--quiet", GENERATOR_REPO, checkout ], { stdio: "inherit" });
+ execFileSync("git", [ "-C", checkout, "checkout", "--quiet", GENERATOR_COMMIT ], {
+ stdio: "inherit"
+ });
+ }
+ return [
+ "flatpak", "run", "--command=python3", `--env=PYTHONPATH=${join(checkout, "node")}`,
+ "org.flatpak.Builder", "-c", GENERATOR_BOOTSTRAP
+ ];
+}
+
+// The aiohttp in org.flatpak.Builder (3.10) rejects GitHub's release responses, whose
+// headers exceed its 8190-byte default, so the generator's sessions get larger limits.
+const GENERATOR_BOOTSTRAP = `\
+import functools, runpy, aiohttp
+aiohttp.ClientSession.__init__ = functools.partialmethod(
+ aiohttp.ClientSession.__init__, max_line_size=65536, max_field_size=65536)
+runpy.run_module("flatpak_node_generator", run_name="__main__", alter_sys=True)
+`;
+
+function dataDir() {
+ return process.env.XDG_DATA_HOME || join(homedir(), ".local/share");
+}
+
+function git(...args: string[]): string {
+ return execFileSync("git", args, { cwd: REPO_ROOT }).toString().trim();
+}
+
+// Only when run as a script — the pure helpers above are imported by the spec.
+if (process.argv[1] === import.meta.filename) {
+ main().catch((err) => {
+ console.error(err instanceof Error ? err.message : err);
+ process.exit(1);
+ });
+}
diff --git a/scripts/flatpak/build-local.spec.ts b/scripts/flatpak/build-local.spec.ts
new file mode 100644
index 0000000000..a769735b4f
--- /dev/null
+++ b/scripts/flatpak/build-local.spec.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { parseIgnoredPaths, useLocalDirSource } from "./build-local.mjs";
+
+const SOURCES = (pin: string) => `\
+ sources:
+ - type: git
+ url: https://github.com/TriliumNext/Trilium.git
+${pin} - generated-sources.json
+ - type: archive
+ url: https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.0.0.tgz
+`;
+
+describe("useLocalDirSource", () => {
+ it("swaps a pinned git source for a dir source and keeps the others", () => {
+ const expected = `\
+ sources:
+ - type: dir
+ path: "/home/user/Trilium"
+ skip:
+ - "node_modules"
+ - "apps/client/dist"
+ - generated-sources.json
+ - type: archive
+ url: https://registry.npmjs.org/@pnpm/exe.linux-x64/-/exe.linux-x64-12.0.0.tgz
+`;
+ const skip = [ "node_modules", "apps/client/dist" ];
+ const commit = " commit: 1234567890abcdef1234567890abcdef12345678\n";
+ const tagged = ` tag: v0.106.0\n${commit}`;
+ for (const pin of [ commit, tagged ]) {
+ expect(useLocalDirSource(SOURCES(pin), "/home/user/Trilium", skip)).toBe(expected);
+ }
+ });
+
+ it("fails on a manifest without the Trilium git source", () => {
+ expect(() => useLocalDirSource("sources: []\n", "/repo", []))
+ .toThrow(/no Trilium git source/);
+ });
+});
+
+describe("parseIgnoredPaths", () => {
+ it("strips directory slashes and drops paths inside another ignored one", () => {
+ const output = ".flatpak-builder/\n.flatpak-builder/ccache/\napps/client/dist/\n"
+ + "apps/client/tsconfig.tsbuildinfo\nnode_modules/\nnode_modules_backup/\n";
+ expect(parseIgnoredPaths(output)).toEqual([
+ ".flatpak-builder", "apps/client/dist", "apps/client/tsconfig.tsbuildinfo",
+ "node_modules", "node_modules_backup"
+ ]);
+ });
+});