From ff94a571c2bd29b35b105ec1d2e160bcd1286b50 Mon Sep 17 00:00:00 2001 From: ZhuchkaTriplesix Date: Sat, 17 Oct 2026 12:58:17 +0300 Subject: [PATCH] docs(macos): installing the unsigned build on macOS 14 and 15+, App Translocation, and the minimum macOS version (#1594, #1591) --- README.md | 20 ++++++++++++++------ docs/macos-signing.md | 22 ++++++++++++++++++++++ 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f3f7fe29..88fedbe5 100644 --- a/README.md +++ b/README.md @@ -151,12 +151,20 @@ flatpak install --user ./Querya-Desktop-*-linux.flatpak Download the Windows installer (`.exe`) or portable archive (`.zip`) from [Releases](https://github.com/QueryaHub/Querya-Desktop/releases). Run the setup to automatically register `.sql` and `.sqlite` file associations. ### macOS -Download the universal `.dmg` from [Releases](https://github.com/QueryaHub/Querya-Desktop/releases), mount the disk image, and drag **Querya Desktop** into your `Applications` folder. - -> **Unsigned builds:** If Gatekeeper blocks the app after installation, run: -> ```bash -> xattr -cr "/Applications/Querya Desktop.app" -> ``` +Requires **macOS 10.15 (Catalina) or later**; the app is a universal build (Apple silicon and Intel). + +1. Download `Querya-Desktop--macos.dmg` from [Releases](https://github.com/QueryaHub/Querya-Desktop/releases), open it and drag **Querya Desktop** into `Applications`. +2. Start it from `Applications`, not from the disk image or `Downloads`: there macOS runs a temporary read-only copy, and the in-app update cannot replace it. + +> **Unsigned builds.** A release built without the Developer ID secrets is ad-hoc signed, and Gatekeeper blocks its first launch: +> - **macOS 14 and earlier:** Control-click (right-click) the app → **Open** → **Open**. +> - **macOS 15 and later:** that no longer works. Try to open the app once, then go to **System Settings → Privacy & Security**, find "Querya Desktop was blocked…" and click **Open Anyway**. +> - Or clear the quarantine flag in Terminal: +> ```bash +> xattr -dr com.apple.quarantine "/Applications/Querya Desktop.app" +> ``` +> +> The unsigned build is not sandboxed and behaves like the signed one (connections, SSH keys, extensions, MCP, in-app updates); only this first-launch step differs. See [macOS signing](docs/macos-signing.md). --- diff --git a/docs/macos-signing.md b/docs/macos-signing.md index 15f1c827..f4cec0db 100644 --- a/docs/macos-signing.md +++ b/docs/macos-signing.md @@ -141,6 +141,28 @@ If you later add plugins that require microphone, camera, or other protected res --- +## Running an unsigned build + +Without the signing secrets the release ships an ad-hoc signed app. It has no App Sandbox (see Entitlements above), so it can reach `~/.querya`, `~/.ssh`, saved SQLite paths, run extensions under `sandbox-exec`, serve MCP and update itself, like the signed build. What differs is Gatekeeper: + +| macOS | First launch | +|---|---| +| 14 and earlier | Control-click the app → **Open** → **Open**. | +| 15 and later | Control-click → Open no longer bypasses Gatekeeper. Open the app once, then **System Settings → Privacy & Security → Open Anyway**. | +| any | `xattr -dr com.apple.quarantine "/Applications/Querya Desktop.app"` | + +Move the app to `/Applications` before the first launch. Started from `~/Downloads` or the disk image, macOS runs it through App Translocation (a read-only copy at a random path): the in-app update refuses to run there and points to the release page instead (#1587). + +Related: secrets are stored in the login keychain, so they work without `keychain-access-groups` and without a provisioning profile (#1586); an update must carry the same Team ID as the installed app when the installed app is signed (#1588). + +## Minimum macOS version + +`MACOSX_DEPLOYMENT_TARGET` is **10.15** in every Xcode configuration, and `LSMinimumSystemVersion` follows it. That is also the highest minimum among the macOS plugins in use (`file_selector_macos` and `url_launcher_macos` need 10.15; `package_info_plus`, `device_info_plus` and the vendored `refresh_rate` need 10.14). Raising it needs no plugin change, lowering it is not possible. + +Rendering above 60 Hz on a ProMotion display needs **macOS 14** or later (`refresh_rate`, see [motion and high refresh](motion-and-high-refresh.md)); on older versions the app runs at 60 Hz. + +--- + ## References - Flutter: [Build and release a macOS app](https://docs.flutter.dev/deployment/macos)