The Flatpak

How the Flatpak is built, what it may reach on the computer and why, and how AetherPak publishes it to flatpak.nocturne.is.

The Flatpak is a fourth Linux package next to the AppImage, the deb and the rpm. Its app id is is.nocturne.Nocturne, the reverse of the project's own domain. The desktop identifier app.nocturne.desktop stays what it is everywhere else: it names the data folder and the single-instance lock, and it cannot be a Flatpak id because an id may not end in .desktop.

The files

File What it is
flatpak/is.nocturne.Nocturne.yml The manifest: GNOME 51 runtime, the Rust and Node SDK extensions, three modules
flatpak/is.nocturne.Nocturne.desktop The desktop entry
flatpak/is.nocturne.Nocturne.metainfo.xml The AppStream description, with screenshots from nocturne.is
flatpak/aetherpak.yaml Where AetherPak pushes the images, how it names the repository and how its page looks
flatpak/site/index.html The repository page at flatpak.nocturne.is
flatpak/shared-modules/ The tray library and intltool modules, copied unchanged from flathub/shared-modules at commit c91a8110
scripts/flatpak-sources.sh Writes the offline Cargo and npm sources into flatpak/generated/
scripts/check_flatpak.py The drift check make check runs through its tests
.github/workflows/flatpak.yml Builds with AetherPak and, when asked, publishes

The manifest builds three modules:

  1. libdrm, for libdrm_amdgpu, which the private engine links and the GNOME runtime does not carry. The version matches the runtime's own libdrm.
  2. libayatana-appindicator, the tray library Tauri loads at run time.
  3. nocturne: the interface (npm ci --offline, npm run build), the program (cargo build --release --locked --offline --features custom-protocol), the third-party notices, and the pinned engine. The engine archive is the one lemonade.lock names for the architecture being built (the manifest lists both, each with only-arches), checked by its sha256, and installed byte for byte into /app/lib/Nocturne/lemonade/: the module neither strips nor splits debug information. The program finds it there the same way the deb does, because Tauri's resource folder for /app/bin/nocturne is /app/lib/Nocturne.

Nothing is downloaded while the module builds. Cargo and npm read the sources scripts/flatpak-sources.sh generates from Cargo.lock and ui/package-lock.json with the flatpak-builder-tools generators at a pinned commit. Those files are generated for every build and never committed, so they cannot fall behind the lockfiles. The script needs uv and the network; it installs nothing outside uv's cache.

scripts/check_flatpak.py fails make check when the engine archives in the manifest differ from lemonade.lock, when the newest release in the metainfo is not the workspace version, when the app id differs between the four files, or when the finish-args differ from the table below.

Build it locally

You need flatpak, flatpak-builder, uv, and the GNOME 51 runtime and SDK with the rust-stable and node24 extensions for the 26.08 SDK, installed for your user. GNOME 51 is the first GNOME runtime whose C library is new enough for the pinned engine (it needs glibc 2.43; GNOME 50 has 2.42).

flatpak install --user flathub org.gnome.Sdk//51 org.gnome.Platform//51 \
    org.freedesktop.Sdk.Extension.rust-stable//26.08 org.freedesktop.Sdk.Extension.node24//26.08
scripts/flatpak-sources.sh
cd flatpak
flatpak-builder --user --force-clean --state-dir=.flatpak-builder --repo=repo build is.nocturne.Nocturne.yml
flatpak build-bundle repo nocturne.flatpak is.nocturne.Nocturne
flatpak install --user ./nocturne.flatpak

Cargo uses the builder's job count (FLATPAK_BUILDER_N_JOBS), so on a shared machine set it low and run the build under the usual resource cap. appstreamcli validate --no-net and desktop-file-validate check the two metadata files.

What the sandbox may reach

The app keeps everything inside its own folders: its data, its settings and the web view's cache live under ~/.var/app/is.nocturne.Nocturne/. It has no access to the home folder or any other folder. Files arrive through the system's file chooser and drag and drop, which hand over only what the person picked, through the documents portal. Opening links and folders goes through the portal too.

Permission Why
--share=ipc Shared memory for the X11 fallback; without it X11 drawing is slow or fails
--socket=wayland Shows the window on a Wayland desktop
--socket=fallback-x11 Shows the window on an X11 desktop, and only there
--device=all The engine's ROCm backend needs /dev/kfd on a discrete AMD GPU, which --device=dri does not expose; Vulkan needs /dev/dri
--socket=pulseaudio Records voice notes and reads the page aloud
--share=network Downloads the models the person agreed to, and carries Online answers and Away from home when they are on; the engine also listens on loopback
--talk-name=org.freedesktop.Notifications The one note that the page is ready; the notification library talks to this service directly, not to the portal
--talk-name=org.kde.StatusNotifierWatcher Registers the tray icon and asks whether the desktop shows one
--own-name=app.nocturne.desktop.SingleInstance The single-instance lock: a second launch hands its file to the running window instead of starting another app
--env=WEBKIT_DISABLE_DMABUF_RENDERER=1 The web view's DMA-BUF renderer shows a blank window inside the sandbox on some graphics drivers

What does not work in the Flatpak yet

  • Start with this computer. The app writes its own start-up entry, which inside the sandbox lands in the app's own folder and is never read. It needs the Background portal.
  • Keeping the computer awake overnight, and knowing the person is away. The sandbox has no access to logind, UPower or the idle monitors on the session bus. Unknown idle time already counts as away and mains power is read from /sys/class/power_supply, so the overnight tidy still runs, but it cannot stop the computer from sleeping during it. The Inhibit portal would cover sleep.
  • The keychain. Without the Secret Service the Online answers key is kept in the owner-only file inside the app's data folder, which the app already falls back to.
  • Sound settings. The button that opens the system's sound settings finds no program inside the sandbox and reports it as unavailable.
  • The quick keep shortcut on Wayland. The command Settings shows is the program inside the sandbox; a desktop shortcut needs flatpak run is.nocturne.Nocturne --quick-capture instead.
  • An inbox folder chosen through the portal is watched by the regular rescan once a minute, since change notifications do not cross the documents portal.

Publishing with AetherPak

.github/workflows/flatpak.yml builds the Flatpak with AetherPak and, when asked, publishes it. AetherPak stores the app as OCI images in GHCR (ghcr.io/agync/nocturne-flatpak) and writes a small static index, a nocturne.flatpakrepo, a .flatpakref per channel and a landing page under https://flatpak.nocturne.is. The remote is named nocturne and titled "Nocturne", so software centres show it under its own name.

The landing page is flatpak/site/index.html, which branding.index_template in aetherpak.yaml names. It is AetherPak's default template restyled as nocturne.is: AetherPak fills in the channels, the install links, the commands and the key fingerprint when it builds the site, so the page uses only the template fields the pinned CLI (v0.34.0) provides. The fonts and icons load from nocturne.is, whose _headers lets this origin use the fonts. To preview it, build the CLI at that tag into a scratch folder and run aetherpak preview --config flatpak/aetherpak.yaml from the repository root. It serves the template with made-up apps but without the logo, icon, colour and footer; for those and for Nocturne's own channels, run aetherpak build-site --config flatpak/aetherpak.yaml --landing-page --allow-unsigned --no-sign against a small records folder and serve the result.

The workflow runs by hand (workflow_dispatch) or from another workflow (workflow_call). It is never started by a push.

Input Default Meaning
ref the triggering ref The tag, branch or commit to build; resolved to one commit that every job builds
tag none (called only) The release tag ref came from, needed to publish to stable
channel stable when called, beta by hand The Flatpak branch
publish false Push the images and deploy the index; without it the build is checked and a .flatpak bundle is uploaded as a workflow artefact. Publishing to stable needs a v* release tag that points at the commit; any other publish goes to beta

Its jobs:

  1. resolve turns ref into one commit and refuses a stable publish that is not a release tag pointing at it. Every later job checks out that commit.
  2. sources generates the offline sources and hands them on as an artefact.
  3. build runs AetherPak's build (with flatpak-builder-lint) in the AetherPak builder container, which is privileged and pinned by digest, once for x86_64 on ubuntu-24.04 and once for aarch64 natively on ubuntu-24.04-arm. The digest is a multi-architecture index, so the same pin runs on both. It sees no secret and cannot push. When publishing, it hands the unsigned repository on as an artefact and turns the build cache off. It still uses the AetherPak build action, whose own setup and cache actions are not pinned; that is acceptable only because nothing secret is reachable from this job.
  4. publish, when publishing, runs in the release-signing environment without privileges. It fails if the key is empty, then signs the images and pushes them with the AetherPak publish-oci action, pinned to the same commit as the build action. It runs once per architecture, each writing its own record; both run on x86_64, because a push only copies the built repository into the registry.
  5. site runs in release-signing. It merges the records of both architectures with the index live at https://flatpak.nocturne.is, signs it with the AetherPak publish-site action and hands the site on as an artefact.
  6. deploy publishes that artefact to GitHub Pages.

A caller grants contents: read, packages: write, pages: write and id-token: write. The two secrets, FLATPAK_GPG_PRIVATE_KEY and FLATPAK_GPG_PASSPHRASE, live in the release-signing environment and are read only by publish and site; no caller passes them. Publishing without a key fails, so the repository is never unsigned.

The release-signing environment must have required reviewers and hold the two secrets, and the v* tag ruleset described in release.md must be in place: the workflow's tag checks assume that only the release App can create or move a release tag.

Before the first publish, a maintainer:

  • runs the workflow by hand once with channel beta and publish on, to prove signing, the push and the index against the real registry before a release depends on them;
  • allows public packages for the organisation, then makes nocturne-flatpak public after the first push, so people can install without signing in to GitHub;
  • sets up the domain once: in Cloudflare DNS adds a flatpak CNAME record to agync.github.io, set the zone's SSL/TLS mode to Full (strict) or add a configuration rule for that host, and in the repository's Pages settings sets the custom domain flatpak.nocturne.is and turns on Enforce HTTPS. Leave the record DNS only until GitHub has issued its certificate for the domain, then switch it to proxied. The site job writes a CNAME file into the site so each deployment keeps the domain. The landing site at nocturne.is stays on Cloudflare Pages;
  • publishes the three screenshots the metainfo names under https://nocturne.is/screenshots/.
Note

Owner decisions needed: the signing key and the GHCR package name. TODO(owner).

Connections

Local graph

Linked from