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:
libdrm, forlibdrm_amdgpu, which the private engine links and the GNOME runtime does not carry. The version matches the runtime's ownlibdrm.libayatana-appindicator, the tray library Tauri loads at run time.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 onelemonade.locknames for the architecture being built (the manifest lists both, each withonly-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/nocturneis/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-captureinstead. - 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:
resolveturnsrefinto one commit and refuses a stable publish that is not a release tag pointing at it. Every later job checks out that commit.sourcesgenerates the offline sources and hands them on as an artefact.buildruns AetherPak's build (withflatpak-builder-lint) in the AetherPak builder container, which is privileged and pinned by digest, once for x86_64 onubuntu-24.04and once for aarch64 natively onubuntu-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.publish, when publishing, runs in therelease-signingenvironment without privileges. It fails if the key is empty, then signs the images and pushes them with the AetherPakpublish-ociaction, 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.siteruns inrelease-signing. It merges the records of both architectures with the index live athttps://flatpak.nocturne.is, signs it with the AetherPakpublish-siteaction and hands the site on as an artefact.deploypublishes 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
betaand 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-flatpakpublic after the first push, so people can install without signing in to GitHub; - sets up the domain once: in Cloudflare DNS adds a
flatpakCNAME record toagync.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 domainflatpak.nocturne.isand turns on Enforce HTTPS. Leave the record DNS only until GitHub has issued its certificate for the domain, then switch it to proxied. Thesitejob writes aCNAMEfile into the site so each deployment keeps the domain. The landing site atnocturne.isstays on Cloudflare Pages; - publishes the three screenshots the metainfo names under
https://nocturne.is/screenshots/.
Owner decisions needed: the signing key and the GHCR package name. TODO(owner).