The Mac app

The same dashboard in its own window, and the fleet in the menubar: what is running, and a way to stop it without finding the tab.

It is a window onto dqx dashboard, not a second dashboard. The page is the one the command serves, from the same address with the same token, and every button runs the same dqx you run in a terminal.

Installing it

dqx desktop install

It builds the app on your Mac and puts it in ~/Applications/dqx.app. The first time takes about a minute, because it fetches Electrobun, the framework the app is built with; after that, a few seconds. Run it again after dqx self-update to bring the app along, which self-update reminds you of: an open app is quit, replaced and opened again. A failed unpack leaves the old app in place.

Built on your own Mac, the app is not quarantined, so macOS opens it without asking. Its sources and Electrobun's cache stay in ~/.local/share/dqx/desktop. Electrobun comes from npm at the exact version and checksum in the app's lockfile, and Electrobun checks the build tool it downloads against its release's checksums.

When the build fails, the command prints the end of what the build said; the whole of it is in ~/Library/Logs/dqx/desktop-build.log.

What it does

• Opening it joins the dashboard that is running, or starts one when nothing is. One you started in a terminal stays yours: the app neither restarts it nor stops it, and a --read-only one stays read only.

• Closing the window leaves the icon in the menubar. Only Quit stops anything, and only a dashboard the app started itself.

• The menubar icon lists what is running, and the rest one level down. Each project has what its card has:

  • Stop or Start.
  • Its addresses: click one to open it in the browser, or use Copy URL to copy it. A project with several sites lists each site's addresses under its name. A running mail inbox is there as well.
  • Editor, Open and Git: the card's open panel, in the same order. Container shell and the database client appear while the project and its database run.

  The menu also has Start at login.

• Links to a site or a repository open in your browser.

The app uses the dqx on your PATH in a login shell, so dqx self-update updates what the app runs as well. Without dqx installed, the window says how to install it.

Start at login

Start at login writes ~/Library/LaunchAgents/nl.dolphiq.dqx.plist, which opens the app in the menubar without a window. Untick it, or delete the file, to undo it. It needs the app in Applications: a build in a checkout moves on the next build.

Where the dashboard writes

A dashboard the app started has no terminal, so its output goes to ~/Library/Logs/dqx/dashboard.log. Each start adds to it, so the first error of a dashboard that keeps failing is still there; the app tries again less and less often, up to once a minute. When the window says the dashboard did not start, that file says why.

A dashboard started in a terminal that restarts with --new-token is joined again with the new token.

dqx dashboard --restart starts the running dashboard again from the dqx binary on disk, which is what dqx self-update does after an update. The window reloads by itself whenever the dashboard it is joined to serves another build, so a new binary needs no Quit and no reopening.

Limits

• Apple silicon only. Electrobun, the framework under the app, does not build for Intel Macs.
• Port 7391. The app always uses the default port. A dashboard started with --port elsewhere is not one it sees.

Working on it

The app lives in desktop/. dqx desktop install builds the copy of it packed into the binary by bun run build; from a checkout:

bun run desktop:dev      # run it from the checkout
bun run desktop:build    # dqx.app in desktop/build, and a DMG when signing
bun run desktop:icons    # after changing site/public/logo.svg or desktop/assets/tray.svg

These use Hutch, Electrobun's build tool, from ~/.hutch. The dev build has its own bundle id, nl.dolphiq.dqx.dev, so dqx desktop install does not quit it.

A build is signed, notarized and wrapped in a DMG for handing out when the Apple credentials are in the environment:

Variable	What it is
ELECTROBUN_DEVELOPER_ID	The "Developer ID Application" identity in the keychain
ELECTROBUN_APPLEAPIKEY, ELECTROBUN_APPLEAPIISSUER, ELECTROBUN_APPLEAPIKEYPATH	An App Store Connect API key, for notarizing

They live in the password manager, never in the repository. Without them the build still produces an app, which macOS will refuse to open on another Mac until somebody allows it in Privacy & Security.