feat(linux): add sandboxed Flatpak packaging

This commit is contained in:
Yuri Karamian committed 2026-11-10 15:14:32 +04:00
1 parent b9074ec550
commit ceb3a7d647
9 files changed
+11676 -13

No files matched your search

+3
View File
@@ -0,0 +1,3 @@
[submodule "packaging/flatpak/shared-modules"]
path = packaging/flatpak/shared-modules
url = https://github.com/flathub/shared-modules.git
+71
View File
@@ -0,0 +1,71 @@
# Flatpak
This builds HelixNotes from the current checkout inside the GNOME 51 SDK. Rust
and Node dependencies are pinned by the existing lockfiles and downloaded before
the sandboxed, offline build. The shared-modules submodule supplies the Ayatana
tray libraries.
## Build
Run from the repository root:
```sh
git submodule update --init packaging/flatpak/shared-modules
flatpak install --user flathub org.flatpak.Builder org.gnome.Platform//51 org.gnome.Sdk//51 org.freedesktop.Sdk.Extension.node24//26.08 org.freedesktop.Sdk.Extension.rust-stable//26.08
flatpak run org.flatpak.Builder --user --force-clean --state-dir=src-tauri/target/flatpak/state --repo=src-tauri/target/flatpak/repo src-tauri/target/flatpak/build packaging/flatpak/com.helixnotes.app.yml
flatpak build-bundle src-tauri/target/flatpak/repo src-tauri/target/flatpak/HelixNotes_1.3.7_x86_64.flatpak com.helixnotes.app stable --runtime-repo=https://dl.flathub.org/repo/flathub.flatpakrepo
```
The commands require a user-local Flathub remote. If only a system remote exists,
add the user remote first:
```sh
flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
```
## Install and run
```sh
flatpak install --user src-tauri/target/flatpak/HelixNotes_1.3.7_x86_64.flatpak
flatpak run com.helixnotes.app
```
Choose vault folders using the folder picker. Flatpak grants access to the chosen
folders through its document portal; the package does not request access to the
whole home directory. Its settings are separate from native installations.
The document portal does not forward external file-change notifications, so this
build checks for changes every two seconds using the existing polling watcher.
Metadata polling can miss edits within the same timestamp second or edits that
preserve an earlier modification time. Reopen the vault to refresh those changes.
The build sets `HELIXNOTES_INSTALL_TYPE=flatpak`, which suppresses the in-app
updater. Install a newer bundle to update this local package. Automatic Flatpak
updates require a hosted repository or a Flathub release; neither is published by
these build commands. The bundle references Flathub for its runtime, which is
installed separately.
Close native HelixNotes before testing: native and Flatpak installations use the
same single-instance application identifier.
## Refresh dependencies
Regenerate both source lists whenever their lockfiles change. The initial lists
were generated with flatpak-builder-tools commit
`9d86d336a39b9af38b86f114b6ce5820fe260f91`:
```sh
uv run --project /path/to/flatpak-builder-tools/node python -m flatpak_node_generator --no-requests-cache --pnpm-store-version v11 --node-sdk-extension org.freedesktop.Sdk.Extension.node24//26.08 -o packaging/flatpak/node-sources.json pnpm pnpm-lock.yaml
uv run /path/to/flatpak-builder-tools/cargo/flatpak-cargo-generator.py -o packaging/flatpak/cargo-sources.json src-tauri/Cargo.lock
```
Keep the pinned pnpm archive/version in the manifest in step with
`package.json`'s `packageManager`. pnpm 11 uses the v11 store; the generator's
default v10 store does not work with it.
The offline install uses `--trust-lockfile` for this reviewed, pinned lockfile.
Flatpak verifies the downloaded sources against the generated checksums. This
keeps pnpm from querying registry metadata and attestations during the offline
build; it does not grant network access to the build sandbox.
A Flathub submission also needs a pinned Git source in place of the local
directory source, release metadata and a content-rating assessment.
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,10 @@
[Desktop Entry]
Type=Application
Name=HelixNotes
Comment=Write and organize local Markdown notes
Exec=helixnotes %f
Icon=com.helixnotes.app
Terminal=false
Categories=Office;
MimeType=text/markdown;text/x-markdown;
Keywords=Markdown;tasks;wiki;
@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
<id>com.helixnotes.app</id>
<metadata_license>CC0-1.0</metadata_license>
<project_license>AGPL-3.0-or-later</project_license>
<name>HelixNotes</name>
<summary>Write and organize local Markdown notes</summary>
<developer id="com.helixnotes">
<name>HelixNotes</name>
</developer>
<description>
<p>HelixNotes stores your notes as standard Markdown files in a folder you
choose. Write in the Markdown editor, organize notes with tags and wiki links,
and find them with full-text search.</p>
<p>The Tasks view gathers checklists from your notes into a list or calendar.</p>
</description>
<launchable type="desktop-id">com.helixnotes.app.desktop</launchable>
<url type="homepage">https://helixnotes.com</url>
<url type="vcs-browser">https://gitlab.com/ArkHost/HelixNotes</url>
<provides>
<binary>helixnotes</binary>
</provides>
<screenshots>
<screenshot type="default">
<caption>Markdown editor</caption>
<image type="source">https://cdn.helixnotes.com/assets/screenshots/screenshot-1.png</image>
</screenshot>
<screenshot>
<caption>Tasks calendar</caption>
<image type="source">https://cdn.helixnotes.com/assets/screenshots/screenshot-2.png</image>
</screenshot>
</screenshots>
</component>
+84
View File
@@ -0,0 +1,84 @@
app-id: com.helixnotes.app
branch: stable
runtime: org.gnome.Platform
runtime-version: '51'
sdk: org.gnome.Sdk
sdk-extensions:
- org.freedesktop.Sdk.Extension.node24
- org.freedesktop.Sdk.Extension.rust-stable
command: helixnotes
finish-args:
- --socket=wayland
- --socket=fallback-x11
- --share=ipc
- --device=dri
- --share=network
- --filesystem=xdg-run/tray-icon:create
- --talk-name=org.kde.StatusNotifierWatcher
- --talk-name=org.freedesktop.FileManager1
build-options:
append-path: /usr/lib/sdk/node24/bin:/usr/lib/sdk/rust-stable/bin
cleanup:
- /include
- /lib/pkgconfig
- /lib/*.a
- /lib/*.la
modules:
- shared-modules/libayatana-appindicator/libayatana-appindicator-gtk3.json
- name: pnpm
buildsystem: simple
build-commands:
- mkdir -p /app/lib/pnpm /app/bin
- cp -a . /app/lib/pnpm/
- ln -s ../lib/pnpm/bin/pnpm.mjs /app/bin/pnpm
cleanup:
- '*'
sources:
- type: archive
url: https://registry.npmjs.org/pnpm/-/pnpm-11.18.0.tgz
sha256: 29c35ca8d2a287988fdee3e0f36e07d9b93783f567b579b7fd5b798a4563dd81
- name: helixnotes
buildsystem: simple
build-options:
env:
CARGO_HOME: /run/build/helixnotes/cargo
CARGO_NET_OFFLINE: 'true'
CARGO_BUILD_JOBS: '4'
XDG_CACHE_HOME: /run/build/helixnotes/flatpak-node/cache
HELIXNOTES_INSTALL_TYPE: flatpak
build-commands:
- pnpm install --offline --frozen-lockfile --trust-lockfile
- pnpm tauri build --no-bundle
- install -Dm755 src-tauri/target/release/helixnotes /app/bin/helixnotes
- install -Dm644 packaging/flatpak/com.helixnotes.app.desktop /app/share/applications/com.helixnotes.app.desktop
- install -Dm644 packaging/flatpak/com.helixnotes.app.metainfo.xml /app/share/metainfo/com.helixnotes.app.metainfo.xml
- install -Dm644 src-tauri/icons/icon.svg /app/share/icons/hicolor/scalable/apps/com.helixnotes.app.svg
- install -Dm644 src-tauri/icons/128x128.png /app/share/icons/hicolor/128x128/apps/com.helixnotes.app.png
- install -Dm644 src-tauri/icons/128x128@2x.png /app/share/icons/hicolor/256x256/apps/com.helixnotes.app.png
- install -Dm644 LICENSE /app/share/licenses/com.helixnotes.app/LICENSE
sources:
- type: dir
path: ../..
skip:
- .git
- .agents
- .codex
- .aws
- .claude
- .env
- .env.*
- node_modules
- .svelte-kit
- .flatpak-builder
- build
- packaging/flatpak/.flatpak-builder
- src-tauri/target
- src-tauri/gen
- cargo-sources.json
- node-sources.json
File diff suppressed because it is too large. Load diff
+28 -13
View File
@@ -11,6 +11,7 @@ use crate::types::FileEvent;
use crate::vault::operations::{is_hidden, read_note_entry_fast};
const IOS_POLL_INTERVAL: Duration = Duration::from_secs(10);
const FLATPAK_POLL_INTERVAL: Duration = Duration::from_secs(2);
const NATIVE_POLL_INTERVAL: Duration = Duration::from_secs(1);
const EVENT_BATCH_INTERVAL: Duration = Duration::from_millis(50);
@@ -20,18 +21,21 @@ enum WatcherBackend {
Poll,
}
const fn watcher_backend_for_target(is_ios: bool) -> WatcherBackend {
if is_ios {
const fn watcher_backend_for_target(is_ios: bool, is_flatpak: bool) -> WatcherBackend {
if is_ios || is_flatpak {
WatcherBackend::Poll
} else {
WatcherBackend::Recommended
}
}
const fn poll_interval_for_backend(backend: WatcherBackend) -> Duration {
match backend {
WatcherBackend::Recommended => NATIVE_POLL_INTERVAL,
WatcherBackend::Poll => IOS_POLL_INTERVAL,
const fn poll_interval_for_target(is_ios: bool, is_flatpak: bool) -> Duration {
if is_ios {
IOS_POLL_INTERVAL
} else if is_flatpak {
FLATPAK_POLL_INTERVAL
} else {
NATIVE_POLL_INTERVAL
}
}
@@ -115,8 +119,12 @@ pub(crate) fn changed_entry(path: PathBuf, event_type: &str, vault_root: &Path)
pub fn start_watcher(app: AppHandle, vault_path: String) -> Result<VaultWatcher, String> {
let (tx, rx) = mpsc::channel();
let backend = watcher_backend_for_target(cfg!(target_os = "ios"));
let config = Config::default().with_poll_interval(poll_interval_for_backend(backend));
let is_ios = cfg!(target_os = "ios");
// Document-portal FUSE paths expose external changes without forwarding
// inotify events. Poll only in Flatpak, keeping native file watchers intact.
let is_flatpak = option_env!("HELIXNOTES_INSTALL_TYPE") == Some("flatpak");
let backend = watcher_backend_for_target(is_ios, is_flatpak);
let config = Config::default().with_poll_interval(poll_interval_for_target(is_ios, is_flatpak));
let mut watcher = match backend {
WatcherBackend::Recommended => VaultWatcher::Recommended(
RecommendedWatcher::new(tx, config).map_err(|e| e.to_string())?,
@@ -222,25 +230,32 @@ mod tests {
#[test]
fn ios_uses_polling_backend() {
assert_eq!(watcher_backend_for_target(true), WatcherBackend::Poll);
assert_eq!(
watcher_backend_for_target(true, false),
WatcherBackend::Poll
);
}
#[test]
fn other_platforms_keep_recommended_backend() {
assert_eq!(
watcher_backend_for_target(false),
watcher_backend_for_target(false, false),
WatcherBackend::Recommended
);
}
#[test]
fn watcher_backends_use_the_expected_intervals() {
fn watcher_targets_use_the_expected_intervals() {
assert_eq!(
poll_interval_for_backend(WatcherBackend::Poll),
poll_interval_for_target(true, false),
Duration::from_secs(10)
);
assert_eq!(
poll_interval_for_backend(WatcherBackend::Recommended),
poll_interval_for_target(false, true),
Duration::from_secs(2)
);
assert_eq!(
poll_interval_for_target(false, false),
Duration::from_secs(1)
);
}