Skip to content

Home

Jump to bottom
Bobby Comet edited this page Aug 15, 2026 · 8 revisions

Appify Migration & Architecture Guide: v1.x / v2.x → v3.0

Overview

Appify 3.0 is a major architectural release. The core engine (isolated profiles, browser detection, launcher generation, Wayland/X11 handling) is unchanged from the mature 2.2.x line, but the entire UI layer was rewritten, and several new capabilities were added on top.

What stays the same What changed
Data App list, URLs, kiosk/gamepad flags, extension records, profiles, logins, cookies Config directory preferred location is now ~/.appify (migration still user-confirmed)
Engine Browser detection, wrapper generation, display-server flags, WebHID, nice/ionice Improved Chromium text-input fixes, Firefox lock handling, Force X11/XWayland option
UI All previous options remain available Full rewrite from GTK4/libadwaita → PyQt6 + Griffin Dark/Light theme
Catalog Built-in apps still exist Now data-driven via remote store.json (no Appify update required to add apps)

Bottom line for upgraders

  • Your existing apps, profiles, and settings are preserved.
  • You do not need to reinstall every PWA just because you moved to 3.0.
  • You do need to regenerate wrappers (or reinstall) if you want the newest Chromium input fixes, Force X11 mode, or updated Firefox lock handling.
  • If you are still on ~/.pwa_manager, use Menu → Migrate to .appify… when ready.

What's New in 3.0

1. PyQt6 Port + Griffin Theme

The entire UI was rewritten from GTK4/libadwaita to PyQt6. Functionality is identical; only the toolkit and visual style changed.

  • Griffin Dark Theme (default) — deep navy backgrounds, blue accents, matching the rest of the Griffin toolset.
  • Griffin Light Theme — fully supported and fixed in 3.0.1+.
  • Toggle lives in the toolbar (Dark Mode / Light Mode).

2. Data-Driven Catalog (store.json)

Apps and extension presets are no longer hard-coded inside Appify.

  • Catalog is fetched from GitHub (store.json), validated, and cached locally (~/.appify/store_cache.json).
  • New default apps and extension presets can ship without an Appify release.
  • The official catalog is protected by GitHub CODEOWNERS.
  • Menu → Refresh Catalog forces a re-fetch.
  • Menu → Restore Default Apps re-applies the catalog (does not touch installed profiles).

3. Launch Button

A prominent ▶ Launch App button lets you test any installed app directly from the manager without opening your application menu.

4. Advanced Options Improvements

All advanced settings are now in a collapsible panel with tooltips:

  • Kiosk Mode
  • GPU Acceleration
  • Force X11/XWayland Mode (new) — routes Chromium-based apps through XWayland to work around upstream Chromium Wayland text-input-v3 bugs
  • WebHID Gamepad
  • Nice / I/O priority
  • Firefox userChrome.css / userContent.css (now editable as raw text fields, not just file paths)

5. Chromium Text-Input Fixes (3.0.2)

  • On X11, Chromium-based wrappers now export GTK_IM_MODULE=xim so text fields accept keystrokes instead of only showing a blinking caret.
  • On Wayland, the new Force X11/XWayland option works around Chromium’s native text-input-v3 issues that can appear or worsen after browser updates.
  • Existing apps need Regenerate All Wrappers (or a reinstall) to pick these up.

6. Custom Icons

  • Auto-download still works (icon.horse → Google → site favicon).
  • You can now browse for a custom PNG/JPEG/GIF/BMP/ICO/SVG.
  • “Reset to Auto” discards the custom icon and re-downloads the favicon.
  • Custom icons are marked in profile.json so future updates do not overwrite them.

7. Sorting, Bulk Actions & Self-Update

  • Sort apps by Name, Category, Recently Used, or Installed First.
  • Install All in Category — installs every missing catalog app in a chosen category.
  • Backup All Installed Apps.
  • Update Settings (Menu) — check for Appify updates, one-click download & install (AppImage or .deb), optional systemd timer for automatic checks (hourly / daily / weekly / custom).

8. Firefox Reliability

  • Opening the extension store (or adding a custom extension) while the app is already running now correctly remotes the URL into the existing window instead of showing “Firefox is already running, but is not responding”.
  • Stale profile locks from crashes are detected and cleared automatically.

9. Categories Expanded

Categories now include (among others):

AI & Search · Productivity · Communication · Social · Streaming · Cloud Gaming · Art & Design · Streaming Tools · Utilities · Shopping · News & Knowledge · Developer Tools · Education · Music · Finance

Migration Paths

From 2.2.x → 3.0

  1. Install Appify 3.0 (.deb or AppImage).
  2. Launch it. Your config is read automatically.
  3. If you are still on ~/.pwa_manager, the migration dialogue appears (or use Menu → Migrate to .appify…).
  4. Optional but recommended: Menu → Regenerate All Wrappers so every installed app picks up the 3.0.2 Chromium input fixes and latest Firefox lock handling.
  5. (Optional) Open Update Settings and enable automatic update checks if desired.

No per-app reinstall is required for a normal 2.2 → 3.0 upgrade.

From 1.x → 3.0

  1. Install Appify 3.0.
  2. On first launch, the config is migrated (apps, global settings).
  3. Complete the .appify directory migration if prompted.
  4. Reinstall each installed PWA once (or use Regenerate All Wrappers after the first successful install of one app) so launch scripts are rebuilt with modern browser detection, Wayland/X11 flags, and the new input fixes.
  5. Re-check Kiosk, Gamepad, and GPU settings for cloud-gaming apps — these flags are reapplied on Install/Update Settings.

Directory Migration (~/.pwa_manager → ~/.appify)

  • Introduced in 2.2.3, still present and recommended in 3.0.
  • User-confirmed only; nothing is deleted.
  • After migration, some browser extensions may appear disabled (browser limitation caused by the path change). Open the app’s browser → extension manager → Repair (or toggle off/on). Ad blockers are the most commonly affected.
  • Trigger anytime: Menu → Migrate to .appify…

Config & Data Locations (3.0)

Item Path
Config ~/.appify/config.json
Profiles ~/.appify/profiles/<slug>/
Launchers ~/.appify/scripts/pwa-launch-<slug>.sh
Desktop files ~/.local/share/applications/pwa-<slug>-manager.desktop
Icons ~/.local/share/icons/hicolor/512x512/apps/<slug>.png
Backups ~/.appify/.backup/<slug>/
Store cache ~/.appify/store_cache.json
Launch log ~/.appify/launch.log

Legacy path ~/.pwa_manager continues to work until you migrate.

Key Behaviour Notes for 3.0

  • Default browser is still auto-detected every startup from xdg-settings / mimeapps / gio.
  • Per-app browser choice is stored in profile.json and is never overwritten by the global default.
  • browser_override (hard lock) and recommended_browser (soft suggestion) from the catalog are respected.
  • Global GPU / x11_fallback / kiosk / nice / ionice defaults live in config.json; per-app values live in profile.json.
  • Firefox CSS is now stored as the actual CSS text in profile.json (userChrome / userContent) and written to <profile>/chrome/ on every install/regenerate.
  • Stale Firefox launch args that still contained --user-data-dir are automatically corrected on startup and wrappers are regenerated.

Comparison: Appify vs Other Linux PWA / Web-App Tools

Feature Appify 3.0 Linux Mint Web App Manager Browser “Install as App” (Chrome/Edge/Brave) Nativefier / Pake WebCatalog Lycan
Engine Your already-installed browser (native / Flatpak / Snap) Your installed browser Same browser instance Bundled Electron or system WebView Bundled / managed Chromium WebKitGTK (wry)
Profile isolation Full per-app profile Per-app profile Shared with main browser profile Separate app data dir Multi-profile / workspaces Per-app profile
True isolation (cookies, extensions, storage) Yes Partial / limited No Yes (separate process) Yes Yes
Uses existing browser Yes (no extra Chromium download) Yes Yes No (bundles or WebView) Usually no No (WebKit)
Browser choice Firefox, Edge, Brave, Chrome, Chromium, Vivaldi, Opera, Ungoogled Multiple installed browsers Only the browser you are using N/A Managed Fixed WebKit
Wayland / X11 aware Full (Ozone flags, compositor detection, Force X11 option) Basic Browser’s own Tool-dependent Limited on Linux Basic
Extension support Per-app presets + custom + store launcher Limited Shared with main profile Possible but manual Limited Built-in ad/tracker blocker
Catalog of popular sites Data-driven store.json (expandable without release) Manual only None None Large commercial catalog Manual
Kiosk / fullscreen Yes Limited Browser dependent Configurable Limited Limited
Gamepad / WebHID Explicit flags + portal check No Browser default No No No
Custom CSS (Firefox) userChrome + userContent editors No No No No No
Custom icons Auto + manual (many formats) Yes Browser icon Yes Yes Yes
Backup / export / import Per-app + full data export/import No No Manual Cloud sync (paid) Manual
Self-update of the manager Built-in (deb + AppImage) + optional timer Distro packages N/A Manual Yes Manual
GUI Full PyQt6 (Griffin theme) Simple GTK Browser UI CLI / simple Polished commercial TUI + CLI
Platform Linux (systemd-based; .deb + AppImage) Linux Mint (and Debian/Ubuntu via package) All platforms the browser supports Cross-platform Cross-platform (Linux experimental) Linux
License / cost GPL-3.0, free GPL, free Free (browser) Open-source, free Freemium Open-source, free
Best for Power users who want isolation, multi-browser, gaming, and deep control Simple one-click web apps on Mint Casual “pin this site” use Portable standalone binaries Multi-account / workspace users Lightweight WebKit-based apps

Summary

  • Browser built-in “Install as App” — simplest, but shares your main profile (no real isolation).
  • Linux Mint Web App Manager — excellent for basic use; lighter feature set than Appify.
  • Nativefier / Pake — produce standalone binaries; heavier (Electron) or WebView-based; no reuse of your existing browser.
  • WebCatalog — strong multi-account / workspace story; commercial; Linux support is secondary.
  • Lycan — minimal WebKit-based manager; good if you specifically want WebKit instead of Chromium/Firefox.
  • Appify — deepest control on Linux when you already have browsers installed and want true per-app isolation, extension presets, Wayland correctness, cloud-gaming flags, backups, and a modern-themed GUI.

Recommended Post-Upgrade Checklist (3.0)

  1. Confirm session type and browsers in the System banner.
  2. Migrate to ~/.appify if you have not already.
  3. Regenerate All Wrappers (especially important for the 3.0.2 text-input fixes).
  4. Test one or two cloud-gaming or frequently used apps with the new Launch button.
  5. Optionally enable automatic Appify updates under Update Settings.
  6. Refresh the catalog if you want the latest default apps and extension presets.

Troubleshooting (3.0-specific)

Typing does not work in Chromium-based app windows (blinking caret only)

  • On X11: regenerate wrappers (GTK_IM_MODULE=xim is now injected).
  • On Wayland: enable Force X11/XWayland Mode in Advanced Options, then regenerate or reinstall the app.

Firefox extension store / custom extension fails with “already running”
Fixed in 3.0. The store now remotes into the existing window or clears stale locks. Regenerate wrappers if you are still on an older wrapper.

Extensions disabled after migrating to ~/.appify
Browser limitation. Open the app → extension manager → Repair / toggle.

Catalog empty or outdated
Menu → Refresh Catalog. Requires network access to GitHub.

Self-update fails
Confirm install type (AppImage vs deb) under Update Settings. AppImage updates overwrite the binary in place; deb uses apt-get via pkexec.

Wrappers still reference old paths after migration
Menu → Regenerate All Wrappers.

Version Timeline (quick reference)

Version Highlights
1.x Initial GTK-based manager, hard-coded browser commands
2.0 Intelligent browser detection, native Wayland/X11, expanded browsers
2.2.x Categories, profile size, Regenerate Wrappers, .appify migration, Export/Import, userChrome
3.0 PyQt6 + Griffin theme, store.json catalog, Launch button, custom icons, bulk actions, self-updater
3.0.1 Light/dark theme fixes
3.0.2 Chromium X11 input fix + Force X11/XWayland option

Appify Migration & Architecture Guide — covers v1.x / v2.x → v3.0 (current as of 3.0.2)
https://github.com/bobbycomet/Appify

Clone this wiki locally