[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.
This commit is contained in:
3 files changed
+250
No files matched your search
@@ -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 (
|
||||
<div className="flex min-h-screen flex-col bg-surface-950 text-surface-50">
|
||||
<Navbar />
|
||||
<DocsLayout
|
||||
title="Desktop App (Windows & Mac)"
|
||||
intro="DashCaddy also ships as a native desktop app — the same dashboard you know from the browser, running in its own window with its own taskbar icon. This guide covers downloading and installing it on Windows and macOS, including the one-time security prompts both operating systems show for new software."
|
||||
>
|
||||
<h2>Download the app</h2>
|
||||
<p>
|
||||
Grab the installer for your platform from the{' '}
|
||||
<a href="https://get.dashcaddy.net" className="text-brand-400 hover:text-brand-300 underline">
|
||||
download page
|
||||
</a>
|
||||
:
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>Windows</strong> — <code>dashcaddy-installer-win-x64.exe</code> (recommended; adds Start Menu and
|
||||
desktop shortcuts) or <code>dashcaddy-installer-win-x64-portable.exe</code> (single file, no install)
|
||||
</li>
|
||||
<li>
|
||||
<strong>macOS (Apple Silicon M1–M4)</strong> — <code>dashcaddy-installer-mac.dmg</code> (drag-install disk
|
||||
image, Apple Silicon build) or <code>dashcaddy-installer-mac-arm64.zip</code>
|
||||
</li>
|
||||
<li>
|
||||
<strong>macOS (Intel)</strong> — <code>dashcaddy-installer-mac-x64.zip</code>
|
||||
</li>
|
||||
<li>
|
||||
<strong>Linux</strong> — <code>dashcaddy-installer-linux-x64.AppImage</code> or{' '}
|
||||
<code>dashcaddy-installer-linux-x64.deb</code> (Debian/Ubuntu)
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
Every release has a <code>SHA256SUMS.txt</code> alongside the files at{' '}
|
||||
<a href="https://get.dashcaddy.net/release/SHA256SUMS.txt" className="text-brand-400 hover:text-brand-300 underline">
|
||||
get.dashcaddy.net/release/SHA256SUMS.txt
|
||||
</a>
|
||||
. Verify your download against it before running anything — with clear limits on what that check does and doesn't prove (see{' '}
|
||||
<a href="#unsigned" className="text-brand-400 hover:text-brand-300 underline">below</a>).
|
||||
</p>
|
||||
|
||||
<blockquote className="border-l-4 border-brand-500/50 bg-brand-500/5 p-4 rounded-r-lg">
|
||||
<p className="text-surface-300">
|
||||
<strong className="text-brand-400">The desktop app is a window, not a second server.</strong> 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.
|
||||
</p>
|
||||
</blockquote>
|
||||
|
||||
<h2 id="verify">Verify your download first</h2>
|
||||
<p>
|
||||
Because the installers are not code-signed yet (see{' '}
|
||||
<a href="#unsigned" className="text-brand-400 hover:text-brand-300 underline">below</a>), 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:
|
||||
</p>
|
||||
<h3>macOS / Linux</h3>
|
||||
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# 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)`}</code></pre>
|
||||
<h3>Windows (PowerShell)</h3>
|
||||
<pre className="mt-4 overflow-x-auto rounded-lg border border-surface-700/50 bg-surface-950/80 p-4 text-sm"><code>{`# 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`}</code></pre>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h2>Install on Windows</h2>
|
||||
<ol>
|
||||
<li>Download <code>dashcaddy-installer-win-x64.exe</code> and run it.</li>
|
||||
<li>
|
||||
If Windows shows <strong>“Windows protected your PC”</strong> (blue SmartScreen), click{' '}
|
||||
<strong>More info</strong>, then <strong>Run anyway</strong>. See{' '}
|
||||
<a href="#unsigned" className="text-brand-400 hover:text-brand-300 underline">Why the security warning?</a>{' '}
|
||||
below.
|
||||
</li>
|
||||
<li>Follow the setup wizard (choose install location — defaults are fine).</li>
|
||||
<li>Launch DashCaddy from the Start Menu or desktop shortcut.</li>
|
||||
</ol>
|
||||
|
||||
<h2>Install on macOS</h2>
|
||||
<h3>From the DMG (recommended, Apple Silicon)</h3>
|
||||
<ol>
|
||||
<li>Download <code>dashcaddy-installer-mac.dmg</code> and double-click to mount it.</li>
|
||||
<li>Drag <strong>DashCaddy Installer</strong> into the <strong>Applications</strong> folder shortcut.</li>
|
||||
<li>Eject the disk image, then launch DashCaddy from Applications.</li>
|
||||
</ol>
|
||||
<h3>From the ZIP (any Mac)</h3>
|
||||
<ol>
|
||||
<li>Download and unzip the file for your Mac (<code>-arm64.zip</code> for Apple Silicon,{' '}
|
||||
<code>-x64.zip</code> for Intel).</li>
|
||||
<li>Drag <strong>DashCaddy Installer.app</strong> into your Applications folder.</li>
|
||||
<li>Launch it from Applications.</li>
|
||||
</ol>
|
||||
|
||||
<h3 id="first-launch-mac">First launch on macOS</h3>
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Try to open the app. You'll see a dialog saying the app can't be verified — click <strong>Cancel</strong> (don't drag it to Trash).</li>
|
||||
<li>
|
||||
<strong>Right-click</strong> (or Control-click) the app in Applications and choose <strong>Open</strong>,
|
||||
then click <strong>Open</strong> again in the confirmation dialog. macOS now allows the app and opens it
|
||||
normally from now on.
|
||||
</li>
|
||||
</ol>
|
||||
<p>
|
||||
On newer macOS versions the right-click route may be hidden. Instead:{' '}
|
||||
<strong>System Settings → Privacy & Security</strong>, scroll to the <strong>Security</strong> section,
|
||||
find the message saying <em>“DashCaddy Installer was blocked”</em>, click{' '}
|
||||
<strong>Open Anyway</strong>, authenticate with your password or Touch ID, then click <strong>Open</strong> in
|
||||
the final confirmation dialog.
|
||||
</p>
|
||||
|
||||
<h2 id="unsigned">Why the security warning?</h2>
|
||||
<p>
|
||||
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{' '}
|
||||
<em>plus</em> 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 <em>unverified</em>.
|
||||
</p>
|
||||
<p>
|
||||
<strong>Unverified is not the same as malicious</strong> — plenty of legitimate open-source software ships
|
||||
unsigned — but it does mean the OS's automated vetting doesn't apply to it.
|
||||
</p>
|
||||
<p>
|
||||
Verifying the SHA256 checksum against the published manifest gives you a <strong>limited integrity
|
||||
check</strong>: 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 <strong>not</strong>{' '}
|
||||
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:
|
||||
</p>
|
||||
<ol>
|
||||
<li>
|
||||
<strong>Download only from <code>get.dashcaddy.net</code></strong> (HTTPS) — not from mirrors, chat links,
|
||||
or third-party sites.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Verify the SHA256 checksum</strong> 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.
|
||||
</li>
|
||||
</ol>
|
||||
<p>
|
||||
What fixes the warnings takes more than a certificate, and differs by platform: on <strong>macOS</strong>,
|
||||
Developer ID signing <em>plus</em> notarization makes Gatekeeper open the app normally. On{' '}
|
||||
<strong>Windows</strong>, 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.
|
||||
</p>
|
||||
|
||||
<h2>Connect the app to your server</h2>
|
||||
<ol>
|
||||
<li>
|
||||
When the app opens, enter your DashCaddy URL — the same address you use in the browser (for example{' '}
|
||||
<code>https://dashcaddy.example.com</code>).
|
||||
</li>
|
||||
<li>Log in with your usual credentials and TOTP code.</li>
|
||||
<li>
|
||||
You're in — the app renders the identical dashboard, and your session stays signed in between launches.
|
||||
</li>
|
||||
</ol>
|
||||
<p>
|
||||
The app needs to reach the same hostname as your browser. If you use a custom TLD (like{' '}
|
||||
<code>dashcaddy.home</code>), make sure the machine running the desktop app also has DashCaddy's root
|
||||
certificate installed (see the{' '}
|
||||
<a href="/docs/installation" className="text-brand-400 hover:text-brand-300 underline">
|
||||
Installation Guide
|
||||
</a>
|
||||
).
|
||||
</p>
|
||||
|
||||
<h2>Troubleshooting the desktop app</h2>
|
||||
<div className="overflow-x-auto">
|
||||
<table className="w-full text-left text-sm">
|
||||
<thead>
|
||||
<tr className="border-b border-surface-700">
|
||||
<th className="py-3 pr-4 font-semibold text-surface-200">Symptom</th>
|
||||
<th className="py-3 pr-4 font-semibold text-surface-200">Likely cause</th>
|
||||
<th className="py-3 font-semibold text-surface-200">Fix</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody className="text-surface-300">
|
||||
<tr className="border-b border-surface-800">
|
||||
<td className="py-3 pr-4">Mac: “can't be opened” again on a later launch</td>
|
||||
<td className="py-3 pr-4">Quarantine flag re-applied after the app file was replaced or moved</td>
|
||||
<td className="py-3">Right-click → Open once more, or System Settings → Privacy & Security → Open Anyway</td>
|
||||
</tr>
|
||||
<tr className="border-b border-surface-800">
|
||||
<td className="py-3 pr-4">Windows: SmartScreen blocks the portable exe</td>
|
||||
<td className="py-3 pr-4">Unsigned binary with no download reputation yet</td>
|
||||
<td className="py-3">More info → Run anyway (after verifying the checksum)</td>
|
||||
</tr>
|
||||
<tr className="border-b border-surface-800">
|
||||
<td className="py-3 pr-4">Checksum doesn't match</td>
|
||||
<td className="py-3 pr-4">Incomplete download, or the file was modified in transit</td>
|
||||
<td className="py-3">Re-download from get.dashcaddy.net and verify again before running</td>
|
||||
</tr>
|
||||
<tr className="border-b border-surface-800">
|
||||
<td className="py-3 pr-4">App opens but shows “connection refused”</td>
|
||||
<td className="py-3 pr-4">Wrong URL, or the DashCaddy host is down</td>
|
||||
<td className="py-3">Check the URL in a browser first. If the browser works, re-type it in the app.</td>
|
||||
</tr>
|
||||
<tr className="border-b border-surface-800">
|
||||
<td className="py-3 pr-4">Certificate warning inside the app</td>
|
||||
<td className="py-3 pr-4">Custom-TLD install without the root cert on this machine</td>
|
||||
<td className="py-3">Install the DashCA root certificate on the computer running the app</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td className="py-3 pr-4">Login works in browser but not the app</td>
|
||||
<td className="py-3 pr-4">Stale cached session after a server restart</td>
|
||||
<td className="py-3">Log out inside the app, then log back in</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
|
||||
<h2>Next steps</h2>
|
||||
<p>
|
||||
With the app connected, head to{' '}
|
||||
<a href="/docs/first-service" className="text-brand-400 hover:text-brand-300 underline">
|
||||
Deploy Your First Service
|
||||
</a>{' '}
|
||||
to add your first application through the App Selector.
|
||||
</p>
|
||||
</DocsLayout>
|
||||
<Footer />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -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',
|
||||
|
||||
@@ -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' },
|
||||
|
||||
Reference in new issue
Block a user