Skip to content

packaging.md

Latest commit

 

History

History
115 lines (84 loc) · 5.51 KB

packaging.md

File metadata and controls

115 lines (84 loc) · 5.51 KB
Raw

Packaging: portable vs installable

Querya Desktop ships (and will ship) two download channels. See epic #379.

Channel Typical artifact Profile data
Portable Querya-Desktop-{ver}-{os}.zip (Flutter bundle) Portable sidecar (QueryaData/) automatically via .portable marker
Installable AppImage, Windows setup, .deb, .rpm, Flatpak Normal OS locations

Portable profile (QueryaData)

Official release zip archives include a .portable marker file out-of-the-box. On launch, Querya detects the marker (or explicit QueryaData / QUERYA_PORTABLE=1) and automatically creates QueryaData/ next to the binary if it does not exist yet.

To run in portable mode:

  1. Use the pre-packaged portable zip (contains .portable marker file out-of-the-box),
  2. or create a .portable or portable.txt file next to the binary,
  3. or create a folder named QueryaData next to the binary,
  4. or set environment variable QUERYA_PORTABLE=1 (also true / yes / on).

Then local data is stored under that folder:

Kind Path under QueryaData/
SQLite DB querya_desktop/querya.db
Themes themes/
Extensions extensions/
Sandbox / audit logs logs/

On Linux AppImage, the install directory is the parent of $APPIMAGE.

Secrets

Connection passwords remain in the OS keyring (flutter_secure_storage / libsecret / Credential Manager / Keychain). Portable mode does not move secrets into QueryaData in v1.

Bundle / application IDs

Platform ID
Linux (APPLICATION_ID) com.queryahub.querya_desktop
macOS (bundle id) com.queryahub.queryaDesktop
Windows (Company / Product) QueryaHub / Querya Desktop

Legacy com.example.* support directories are migrated once into the new paths (see AppDataRoot.migrateLegacySupportIfNeeded).

Related code

  • lib/core/storage/app_data_root.dart — portable detection, support-dir redirect, id migration
  • Updater packaging context: lib/core/updater/installers/update_install_context.dart
  • Release workflow: .github/workflows/release.yml

Linux distro packages

All installable Linux formats reuse the same Flutter build/linux/x64/release/bundle payload as the portable zip and AppImage.

Format Build script Install
.deb scripts/linux/build_deb.sh sudo apt install ./Querya-Desktop-{ver}-linux.deb
.rpm scripts/linux/build_rpm.sh sudo dnf install ./Querya-Desktop-{ver}-linux.rpm
Flatpak scripts/linux/build_flatpak.sh flatpak install --user ./Querya-Desktop-{ver}-linux.flatpak
AUR packaging/linux/aur/ yay -S querya-desktop (CI publishes on Release when AUR_SSH_PRIVATE_KEY is set)

Runtime dependencies (deb/rpm): GTK 3, libsecret, GLib; app indicator recommended for tray.

Updater policy

Install type In-app updater
Portable zip / AppImage Downloads matching release asset (zip or AppImage)
.deb / .rpm Use apt / dnf (or distro equivalent); in-app install is not offered
Flatpak Use flatpak update (FLATPAK_ID / managed runtime — see update_install_context.dart)
Snap Use snap refresh when/if a Snap build ships

Flatpak sandbox notes

The bundled Flatpak grants network, home, and D-Bus access to the freedesktop secrets service (libsecret). Some database setups (Unix sockets outside $HOME, custom TLS stores) may need extra permissions, e.g.:

flatpak override --user com.queryahub.querya_desktop --filesystem=/var/run/postgresql:ro

Flathub submission uses packaging/linux/flatpak/com.queryahub.querya_desktop.flathub.yml (downloads release zip with checksum), while local build script uses packaging/linux/flatpak/com.queryahub.querya_desktop.yml.

APT and DNF repository (repo.querya.app)

The Release workflow job publish-linux-repo runs scripts/linux/publish_package_repo.sh after the GitHub Release is created. It adds the new .deb / .rpm to the gh-pages branch of QueryaHub/repo, regenerates the APT indexes (apt-ftparchive, signed InRelease / Release.gpg) and the DNF metadata (createrepo_c, signed packages and repomd.xml.asc). Older versions stay in the pool, so users can pin them.

The job is skipped while its secrets are not set, like the AUR job.

One-time setup:

  1. Create a signing key without a passphrase: gpg --quick-generate-key "Querya Packages <packages@querya.app>" rsa4096 sign never.
  2. Add repository secrets in QueryaHub/Querya-Desktop: PACKAGE_REPO_GPG_PRIVATE_KEY (gpg --armor --export-secret-keys <fpr>) and PACKAGE_REPO_TOKEN (a token with write access to QueryaHub/repo).
  3. In QueryaHub/repo, serve the gh-pages branch with GitHub Pages and set the custom domain repo.querya.app (DNS CNAME to queryahub.github.io).
  4. Run a release (or re-run publish-linux-repo) and check https://repo.querya.app/gpg.key and https://repo.querya.app/apt/dists/stable/InRelease.

Rotating the key means re-running the job and asking users to refresh gpg.key.