Flatpak Packaging for Hyprnote

This document describes how to build Hyprnote as a Flatpak and submit it to Flathub.

Overview

Hyprnote uses the "build from source" strategy for Flatpak packaging, which is the preferred approach for Flathub. This means the entire application is built inside the Flatpak sandbox using vendored dependencies.

Prerequisites

Install the required tools:

# Install Flatpak and flatpak-builder
sudo apt install flatpak flatpak-builder

# Add Flathub repository
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Install GNOME runtime and SDK
flatpak install flathub org.gnome.Platform//47 org.gnome.Sdk//47

# Install SDK extensions for Rust and Node
flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//24.08
flatpak install flathub org.freedesktop.Sdk.Extension.node22//24.08

Install the flatpak-builder-tools for generating vendored dependencies:

# Clone flatpak-builder-tools
git clone https://github.com/nickvidal/flatpak-builder-tools.git

# For Node/pnpm dependencies
pip install aiohttp toml

# For Cargo dependencies
pip install toml

Generating Vendored Dependencies

Before building the Flatpak, you need to generate JSON files containing all vendored dependencies. These files allow the build to proceed offline, which is required by Flathub.

Generate pnpm dependencies

From the repository root:

# Generate pnpm-sources.json
python3 flatpak-builder-tools/node/flatpak-node-generator.py pnpm \
  -o apps/desktop/flatpak/pnpm-sources.json \
  pnpm-lock.yaml

Generate Cargo dependencies

From the repository root:

# Generate cargo-sources.json
python3 flatpak-builder-tools/cargo/flatpak-cargo-generator.py \
  -d Cargo.lock \
  -o apps/desktop/flatpak/cargo-sources.json

Building Locally

Once the vendored dependency files are generated, you can build the Flatpak locally:

# Build and install to user Flatpak
flatpak-builder --user --install --force-clean \
  flatpak-build-dir \
  apps/desktop/flatpak/com.hyprnote.Hyprnote.yml

Running the Flatpak

After building and installing:

flatpak run com.hyprnote.Hyprnote

Debugging

To debug inside the Flatpak sandbox:

# Open a shell inside the sandbox
flatpak run --devel --command=sh com.hyprnote.Hyprnote

# Inside the sandbox, you can inspect /app and run the binary directly
ls /app/bin/
/app/bin/hyprnote

Flathub Submission

Preparation Checklist

Before submitting to Flathub, ensure:

The manifest builds successfully with flatpak-builder
The app runs correctly via flatpak run com.hyprnote.Hyprnote
All vendored dependencies are up to date
The metainfo.xml file has valid screenshots and descriptions
The desktop file has correct categories and keywords

Submission Process

Fork the flathub/flathub repository on GitHub

Clone your fork and checkout the new-pr branch:

git clone --branch=new-pr git@github.com:YOUR_USERNAME/flathub.git
cd flathub

Create a new branch for your app:
```
git checkout -b com.hyprnote.Hyprnote
```

Create the app directory and copy files:

mkdir com.hyprnote.Hyprnote
cp /path/to/hyprnote/apps/desktop/flatpak/com.hyprnote.Hyprnote.yml com.hyprnote.Hyprnote/
cp /path/to/hyprnote/apps/desktop/flatpak/com.hyprnote.Hyprnote.desktop com.hyprnote.Hyprnote/
cp /path/to/hyprnote/apps/desktop/flatpak/com.hyprnote.Hyprnote.metainfo.xml com.hyprnote.Hyprnote/
cp /path/to/hyprnote/apps/desktop/flatpak/pnpm-sources.json com.hyprnote.Hyprnote/
cp /path/to/hyprnote/apps/desktop/flatpak/cargo-sources.json com.hyprnote.Hyprnote/

Update the manifest to use a git source instead of a local directory:

sources:
  - type: git
    url: https://github.com/fastrepl/hyprnote.git
    tag: desktop_vX.Y.Z  # Use the release tag
    commit: abc123...     # Include the commit hash

Commit and push:

git add .
git commit -m "Add com.hyprnote.Hyprnote"
git push origin com.hyprnote.Hyprnote

Open a pull request from your branch to the new-pr branch of flathub/flathub
Respond to review comments from Flathub maintainers

After Approval

Once approved:

Flathub creates a dedicated repository: flathub/com.hyprnote.Hyprnote
You are invited as a maintainer
Future updates are done by pushing to that repository

Updating the Flatpak

When releasing a new version:

Update the version in com.hyprnote.Hyprnote.metainfo.xml
Regenerate vendored dependencies if dependencies changed
Update the git source tag/commit in the Flathub manifest
Push changes to the Flathub app repository

File Structure

apps/desktop/
  flatpak/
    com.hyprnote.Hyprnote.yml        # Flatpak manifest
    com.hyprnote.Hyprnote.desktop    # Desktop entry file
    com.hyprnote.Hyprnote.metainfo.xml  # AppStream metadata
    pnpm-sources.json                # Vendored pnpm dependencies (generated)
    cargo-sources.json               # Vendored Cargo dependencies (generated)
  src-tauri/
    tauri.conf.flatpak.json          # Tauri config for Flatpak (updater disabled)

Permissions

The Flatpak manifest includes the following permissions:

Display: Wayland and X11 fallback for GUI
Audio: PulseAudio for microphone and speaker capture
Network: For cloud AI services and calendar sync
Notifications: For meeting reminders and alerts
System Tray: For background operation indicator
Filesystem: Access to Documents and Downloads folders

Troubleshooting

Build fails with missing dependencies

Regenerate the vendored dependency files:

python3 flatpak-builder-tools/node/flatpak-node-generator.py pnpm -o apps/desktop/flatpak/pnpm-sources.json pnpm-lock.yaml
python3 flatpak-builder-tools/cargo/flatpak-cargo-generator.py -d Cargo.lock -o apps/desktop/flatpak/cargo-sources.json

Audio not working

Ensure PulseAudio is running on your system. The Flatpak uses --socket=pulseaudio for audio access.

System tray icon not showing

Some desktop environments require additional configuration for StatusNotifier support. The manifest includes --talk-name=org.kde.StatusNotifierWatcher for tray icon support.

Distribution