From b558d3285e879a677e598ceabaa0726c2e21daa9 Mon Sep 17 00:00:00 2001 From: Krystie Date: Wed, 23 Sep 2026 01:09:01 -0700 Subject: [PATCH] [grade=B urn:ump:am2r4i57ie4wsfionhgqw7h5eclpkhjyqlydqjuqsp3poukcplga] docs: Desktop App (Windows & Mac) guide New /docs/desktop-app: download table with per-platform filenames, SHA256 verification vs published SHA256SUMS.txt (end-anchored grep, tested against the real manifest format), honest unsigned-app framing (limited same-origin integrity check, NOT a safety guarantee), SmartScreen/Gatekeeper explained as identity+notarization+reputation signals, full macOS Open Anyway flow, troubleshooting table. Registered in DocsLayout sidebar + /docs index. --- src/app/docs/desktop-app/page.tsx | 244 +++++++++++++++++++++++++++++ src/app/docs/page.tsx | 5 + src/components/docs/DocsLayout.tsx | 1 + 3 files changed, 250 insertions(+) create mode 100644 src/app/docs/desktop-app/page.tsx diff --git a/src/app/docs/desktop-app/page.tsx b/src/app/docs/desktop-app/page.tsx new file mode 100644 index 0000000..de073c9 --- /dev/null +++ b/src/app/docs/desktop-app/page.tsx @@ -0,0 +1,244 @@ +import Navbar from '@/components/Navbar'; +import Footer from '@/components/Footer'; +import DocsLayout from '@/components/docs/DocsLayout'; + +export default function DocsDesktopAppPage() { + return ( +
+ + +

Download the app

+

+ Grab the installer for your platform from the{' '} + + download page + + : +

+
    +
  • + Windows — dashcaddy-installer-win-x64.exe (recommended; adds Start Menu and + desktop shortcuts) or dashcaddy-installer-win-x64-portable.exe (single file, no install) +
    • +
  • + macOS (Apple Silicon M1–M4) — dashcaddy-installer-mac.dmg (drag-install disk + image, Apple Silicon build) or dashcaddy-installer-mac-arm64.zip +
    • +
  • + macOS (Intel) — dashcaddy-installer-mac-x64.zip +
    • +
  • + Linux — dashcaddy-installer-linux-x64.AppImage or{' '} + dashcaddy-installer-linux-x64.deb (Debian/Ubuntu) +
    • +
+

+ Every release has a SHA256SUMS.txt alongside the files at{' '} + + get.dashcaddy.net/release/SHA256SUMS.txt + + . Verify your download against it before running anything — with clear limits on what that check does and doesn't prove (see{' '} + below). +

+ +
+

+ The desktop app is a window, not a second server. It connects to + your DashCaddy host over the network — all your services, data, and configuration stay on the server where + you installed DashCaddy. Nothing is duplicated on your desktop. +

+
+ +

Verify your download first

+

+ Because the installers are not code-signed yet (see{' '} + below), checksum + verification is the strongest check you can do before running one. It confirms the file you downloaded is + byte-for-byte the file that was published: +

+

macOS / Linux

+ 
{`# from your Downloads folder
+curl -O https://get.dashcaddy.net/release/SHA256SUMS.txt
+grep -E "dashcaddy-installer-mac\\.dmg$" SHA256SUMS.txt | shasum -a 256 -c -
+# (\$ anchors the filename at end of line, so exactly one manifest entry is
+#  selected. Should print: dashcaddy-installer-mac.dmg: OK)`}
+

Windows (PowerShell)

+ 
{`# from your Downloads folder
+Invoke-WebRequest https://get.dashcaddy.net/release/SHA256SUMS.txt -OutFile SHA256SUMS.txt
+Get-FileHash dashcaddy-installer-win-x64.exe -Algorithm SHA256
+# compare the hash to the matching line in SHA256SUMS.txt`}
+

+ If a hash doesn't match, don't run the file — re-download it first, and if it still mismatches, + don't assume your machine is at fault: the published manifest itself could be stale or wrong. Report it + instead. +

+ +

Install on Windows

+
    +
  1. Download dashcaddy-installer-win-x64.exe and run it.
    2. +
  2. + If Windows shows “Windows protected your PC” (blue SmartScreen), click{' '} + More info, then Run anyway. See{' '} + Why the security warning?{' '} + below. +
    3. +
  3. Follow the setup wizard (choose install location — defaults are fine).
    4. +
  4. Launch DashCaddy from the Start Menu or desktop shortcut.
    5. +
+ +

Install on macOS

+

From the DMG (recommended, Apple Silicon)

+
    +
  1. Download dashcaddy-installer-mac.dmg and double-click to mount it.
    2. +
  2. Drag DashCaddy Installer into the Applications folder shortcut.
    3. +
  3. Eject the disk image, then launch DashCaddy from Applications.
    4. +
+

From the ZIP (any Mac)

+
    +
  1. Download and unzip the file for your Mac (-arm64.zip for Apple Silicon,{' '} + -x64.zip for Intel).
    2. +
  2. Drag DashCaddy Installer.app into your Applications folder.
    3. +
  3. Launch it from Applications.
    4. +
+ +

First launch on macOS

+

+ Because the app isn't notarized yet, macOS Gatekeeper will stop it the first time. That's a + one-time step — macOS remembers your choice: +

+
    +
  1. Try to open the app. You'll see a dialog saying the app can't be verified — click Cancel (don't drag it to Trash).
    2. +
  2. + Right-click (or Control-click) the app in Applications and choose Open, + then click Open again in the confirmation dialog. macOS now allows the app and opens it + normally from now on. +
    3. +
+

+ On newer macOS versions the right-click route may be hidden. Instead:{' '} + System Settings → Privacy & Security, scroll to the Security section, + find the message saying “DashCaddy Installer was blocked”, click{' '} + Open Anyway, authenticate with your password or Touch ID, then click Open in + the final confirmation dialog. +

+ +

Why the security warning?

+

+ Windows SmartScreen and macOS Gatekeeper aren't a single check — they combine developer-identity + requirements (on Windows, a paid code-signing certificate; on macOS, Developer ID signing{' '} + plus Apple's notarization scan — the ticket Apple attaches isn't itself a signature, + it's Apple's verdict that the signed app passed a malware check) with reputation and other + security signals. DashCaddy currently has none of these, so the OS treats it as unverified. +

+

+ Unverified is not the same as malicious — plenty of legitimate open-source software ships + unsigned — but it does mean the OS's automated vetting doesn't apply to it. +

+

+ Verifying the SHA256 checksum against the published manifest gives you a limited integrity + check: it confirms the file you downloaded matches, byte for byte, what the release server published + — so it detects a truncated or corrupted download, or tampering in transit. It does not{' '} + prove the software itself is safe: the manifest lives on the same server as the binaries, so a compromised + server could replace both. Checksum comparison is a useful habit, not a substitute for code signing — and + signing/notarization is exactly what's on the roadmap to close that gap. In the meantime: +

+
    +
  1. + Download only from get.dashcaddy.net (HTTPS) — not from mirrors, chat links, + or third-party sites. +
    2. +
  2. + Verify the SHA256 checksum using the steps above, and treat a mismatch as a file you + should never run. Note that a persistent mismatch across fresh downloads can also mean the published + manifest itself is stale or wrong — either way, don't run the file; report it instead. +
    3. +
+

+ What fixes the warnings takes more than a certificate, and differs by platform: on macOS, + Developer ID signing plus notarization makes Gatekeeper open the app normally. On{' '} + Windows, code signing removes the unidentified-publisher state, but SmartScreen can still + warn until the binary builds up download reputation over time. Both are on the roadmap. +

+ +

Connect the app to your server

+
    +
  1. + When the app opens, enter your DashCaddy URL — the same address you use in the browser (for example{' '} + https://dashcaddy.example.com). +
    2. +
  2. Log in with your usual credentials and TOTP code.
    3. +
  3. + You're in — the app renders the identical dashboard, and your session stays signed in between launches. +
    4. +
+

+ The app needs to reach the same hostname as your browser. If you use a custom TLD (like{' '} + dashcaddy.home), make sure the machine running the desktop app also has DashCaddy's root + certificate installed (see the{' '} + + Installation Guide + + ). +

+ +

Troubleshooting the desktop app

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SymptomLikely causeFix
Mac: “can't be opened” again on a later launchQuarantine flag re-applied after the app file was replaced or movedRight-click → Open once more, or System Settings → Privacy & Security → Open Anyway
Windows: SmartScreen blocks the portable exeUnsigned binary with no download reputation yetMore info → Run anyway (after verifying the checksum)
Checksum doesn't matchIncomplete download, or the file was modified in transitRe-download from get.dashcaddy.net and verify again before running
App opens but shows “connection refused”Wrong URL, or the DashCaddy host is downCheck the URL in a browser first. If the browser works, re-type it in the app.
Certificate warning inside the appCustom-TLD install without the root cert on this machineInstall the DashCA root certificate on the computer running the app
Login works in browser but not the appStale cached session after a server restartLog out inside the app, then log back in
+
+ +

Next steps

+

+ With the app connected, head to{' '} + + Deploy Your First Service + {' '} + to add your first application through the App Selector. +

+ +
+ ); +} diff --git a/src/app/docs/page.tsx b/src/app/docs/page.tsx index 55ddf78..43ba5a0 100644 --- a/src/app/docs/page.tsx +++ b/src/app/docs/page.tsx @@ -13,6 +13,11 @@ const docs = [ title: 'Installation Guide', description: 'Installer-based and manual setup paths, prerequisites, and first launch expectations.', }, + { + href: '/docs/desktop-app', + title: 'Desktop App (Windows & Mac)', + description: 'Install the native desktop app, get past the one-time SmartScreen/Gatekeeper prompts, and connect it to your server.', + }, { href: '/docs/first-service', title: 'Deploy Your First Service', diff --git a/src/components/docs/DocsLayout.tsx b/src/components/docs/DocsLayout.tsx index 29f7b9a..b0ccf2f 100644 --- a/src/components/docs/DocsLayout.tsx +++ b/src/components/docs/DocsLayout.tsx @@ -3,6 +3,7 @@ import Link from 'next/link'; const docsLinks = [ { href: '/docs/overview', label: 'Product Overview' }, { href: '/docs/installation', label: 'Installation Guide' }, + { href: '/docs/desktop-app', label: 'Desktop App (Windows & Mac)' }, { href: '/docs/first-service', label: 'Deploy Your First Service' }, { href: '/docs/integrations', label: 'Infrastructure Integrations' }, { href: '/docs/premium', label: 'Premium Features' },