@martijn-on-fhir/docker-desktop-mx 1.23.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martijn Schimmel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# Docker Desktop MX
+
+A desktop client for a Docker daemon: the everyday work of Docker Desktop (containers,
+images, volumes, networks, compose and logs) without Docker Desktop itself. It was made for
+Docker running in WSL on Windows, but it talks to any daemon you can reach.
+
+The app does **not** manage the engine. The daemon already runs somewhere (a WSL distro, a
+Linux host, Colima, Docker Desktop); Docker Desktop MX is only the client.
+
+![The containers page, grouped by compose project, with live CPU and memory per container](docs/application.png)
+
+## Features
+
+- **Dashboard**: engine status, CPU/memory/network charts, disk usage, and a prune dialog.
+- **Containers**: grouped by compose project; start, stop, restart, pause and remove, also in
+  bulk. The detail page has live logs, inspect, stats, a terminal, a file browser (download
+  and upload by drag and drop) and a one-click diagnosis you can paste into an issue.
+- **Images**: pull with per-layer progress, run a container from an image, check the registry
+  for newer versions, and recreate compose containers after an update.
+- **Volumes and networks**: list, remove and prune; back up a volume to a `.tar` and restore it.
+- **Compose**: projects as a group, with `up` and `down`.
+- **Logs**: the logs of all running containers merged in one view, with a level filter.
+- **Terminal**: a root shell on the Docker host itself, next to the per-container shells.
+- **Claude** (optional): with your own Claude API key, a Claude tab on every container and on
+  the host terminal that reads logs and inspect data and suggests fixes or commands.
+- **Docker contexts**: switch between them from the status bar.
+- **Command palette**: `Ctrl+K` (`Cmd+K` on macOS) jumps to any page, container, image, volume
+  or network.
+- **Background**: the app keeps running in the system tray and sends a notification when a
+  container crashes or becomes unhealthy. It can start at login.
+- **Updates**: the Windows installer version updates itself.
+- **Languages and themes**: English (the default) and Dutch, chosen under Settings.
+  Technical terms stay in English. Light and dark theme, toggled in the header.
+
+## Requirements
+
+- **A running Docker daemon.** The app finds it the same way the `docker` CLI does:
+  `DOCKER_HOST` first, then the current docker context, then the platform default
+  (`npipe:////./pipe/docker_engine` on Windows, `/var/run/docker.sock` elsewhere).
+- **The `docker` CLI with the compose plugin**, only for compose `up` and `down`. Everything
+  else goes through the Engine API directly.
+- **A Claude API key**, only for the Claude tab.
+
+### Docker in WSL, without Docker Desktop
+
+With Docker Engine installed inside a WSL distro, make the daemon listen on localhost as well
+as on its socket. In the distro, edit `/etc/docker/daemon.json`:
+
+```json
+{ "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2375"] }
+```
+
+On systemd distros, also remove the `-H fd://` flag from the service, because it conflicts
+with `hosts`. Then restart Docker. On Windows, point a context at it:
+
+```bash
+docker context create wsl --docker host=tcp://localhost:2375
+docker context use wsl
+```
+
+Port 2375 has no authentication, so bind it to `127.0.0.1` only, as above. If the distro is not
+running, the app says so and offers to start it.
+
+### A Docker host over SSH
+
+A context with an `ssh://` endpoint works too, like it does for the `docker` CLI. Add one under
+**Settings → Servers** (which also tests the connection and can trust a new host key after you
+compare its fingerprint), or with the CLI:
+
+```bash
+docker context create server --docker host=ssh://user@192.168.1.16
+```
+
+The app logs in and runs `docker system dial-stdio` on the server, so nothing has to listen on
+TCP there. What it needs:
+
+- **The server in `~/.ssh/known_hosts`.** The app never accepts an unknown host key by itself:
+  trust it under Settings → Servers after comparing the fingerprint, or connect once with
+  `ssh user@host`. A changed host key is refused; that one you check with `ssh-keygen -R`.
+- **A key without a passphrase prompt**: the ssh agent (`SSH_AUTH_SOCK`, or the OpenSSH agent
+  service on Windows), or `~/.ssh/id_ed25519`, `id_ecdsa` or `id_rsa` without a passphrase.
+  `~/.ssh/config` is not read, so put the user name in the address.
+- **The `docker` CLI on the server**, and the user in its `docker` group.
+
+## Installing
+
+- **Windows installer**: download `Docker-Desktop-MX-Setup.exe` from the latest
+  [release on Codeberg](https://codeberg.org/MartijnSchimmel/docker-desktop-mx/releases). It is
+  not code-signed, so SmartScreen asks for confirmation the first time.
+- **npm**: `npx @martijn-on-fhir/docker-desktop-mx`, or `npm install -g @martijn-on-fhir/docker-desktop-mx`
+  and then `docker-desktop-mx`. The first start downloads Electron (about 100 MB). Starting at
+  login and self-updating only work with the installer.
+- **From source**: see [Development](#development).
+
+## Using Claude
+
+Open **Settings → Claude** and paste an API key from the
+[Claude Console](https://console.anthropic.com/). The key is stored encrypted on this computer
+and is readable only by your user account. Each question costs a little API usage, billed to
+your own account.
+
+The same screen picks the model: Opus 5 (the default) reasons best about a stubborn problem,
+Sonnet 5 and Haiku 4.5 answer faster and cost less.
+
+Claude can only read: container logs, events, stats, inspect data, compose projects and, on
+the host terminal, what the terminal shows. Secrets such as passwords and tokens are masked
+before anything is sent. Claude never acts on its own. It can propose an action, such as a
+restart, which runs only when you click it. It can also propose a command, which goes into
+the terminal prompt; you decide whether to press Enter.
+
+## Development
+
+Built with **Angular 22** (standalone, zoneless, signals) in the renderer, **Electron 44** as
+the shell, and **dockerode** in the main process. Needs Node 20 or later and a running daemon.
+
+```bash
+npm install
+npm start
+```
+
+The original design notes are in [`docs/plan.md`](docs/plan.md), and how releases work is in
+[`RELEASING.md`](RELEASING.md). Both are in Dutch.
+
+### Scripts
+
+| Command                    | What it does                                                 |
+| -------------------------- | ------------------------------------------------------------ |
+| `npm start`                | builds the app and starts it, the way the installer does     |
+| `npm run dev`              | the same, with `ng serve` behind it so the renderer reloads  |
+| `npm run build`            | production build of the renderer                             |
+| `npm run electron:compile` | compiles `electron/` and bundles the preload                 |
+| `npm run electron:build`   | both builds, ready to run with `electron .`                  |
+| `npm run electron:package` | builds everything and makes an installer with electron-builder |
+| `npm run lint`             | ESLint over TypeScript, the configs and the Angular templates |
+| `npm run lint:fix`         | the same, with autofix                                       |
+| `npm test`                 | renderer unit tests (Vitest + jsdom)                         |
+| `npm run test:electron`    | main process unit tests (Vitest, node)                       |
+| `npm run smoke`            | starts the built app and checks the whole chain end to end   |
+| `npm run release`          | semantic-release; runs in CI, not by hand                    |
+
+The app only runs inside Electron. In a plain browser `window.electron` does not exist and the
+shell fails straight away, which is why there is no script that serves only the renderer.
+
+### Layout
+
+```
+electron/            main process (TypeScript, compiled to CommonJS)
+  api.ts             the contract between main/preload and the renderer
+  channels.ts        IPC channel names, without imports
+  ipc.ts             the only place where channels are attached to ipcMain
+  preload.ts         contextBridge, the renderer's only window into main
+  main.ts            window, tray, notifications and app lifecycle
+  docker-client.ts   daemon connection and readable errors
+  i18n.ts            language of the texts main produces
+  *.ts               one file per feature (containers, images, logs, exec, compose, ...)
+  *.spec.ts          unit tests, kept out of dist-electron
+
+src/
+  styles.css         Tailwind 4 and the theme tokens
+  app/core/          stores and services without UI of their own
+  app/shell/         header, sidebar, status bar, table, dialogs, toasts, command palette
+  app/pages/         one folder per route
+  app/i18n/          the dictionaries: en/ is the source, nl/ follows the same shape
+  testing/           the fake window.electron for renderer tests
+
+scripts/smoke.js     starts the built app against a real daemon
+.forgejo/workflows/  CI on every branch, release on main
+eslint-rules/        two custom formatting rules
+```
+
+### Adding a feature that needs main
+
+Type it in `electron/api.ts`, attach the channel in `electron/ipc.ts` (validate the input with
+zod there), and add the wrapper in `electron/preload.ts`. Angular picks up the type through
+`src/electron.d.ts` (`window.electron`).
+
+### Translations
+
+Every visible text in the renderer comes from `src/app/i18n/`. Add a key to the English file in
+`en/`, and the compiler requires the same key in `nl/`. A text that includes a number or a name
+is a function, so each language can handle plurals its own way. Texts made in the main process
+use `t({ en: '…', nl: '…' })` from `electron/i18n.ts`. The tests run in Dutch
+(`src/testing/setup.ts`, `electron/test-setup.ts`). Each area also has tests that switch to
+English.
+
+### Theme
+
+The tokens in `src/styles.css` are a `--color-ink-*` ramp, where a lower number means more
+contrast with the page, plus `accent`, `ok`, `warn`, `danger` and `panel`.
+`:root[data-theme='dark']` overrides the same names, so every Tailwind utility follows the
+theme without template changes. `src/main.ts` sets the theme before Angular starts, which
+avoids a light flash with a dark theme.
+
+Filters on the list pages and the log view toggles are remembered (`app/core/preferences.ts`).
+Search fields deliberately are not: a search term still active after a restart looks as if
+half your containers have gone.
+
+### Code style
+
+The lint config enforces the house style:
+- lines up to 200 characters, and always braces;
+- blank lines around control statements, and one after the `{` of a function declaration;
+- parameters on one line as long as it fits within 150 characters.
+
+Two custom rules for this live in `eslint-rules/`. There is deliberately **no Prettier**,
+because it conflicts with these rules. `angular-eslint` also lints the `.html` templates.
+
+Commits follow **conventional commits**, which commitlint checks through
+`.husky/commit-msg`. The messages decide the version number: every push to `main` releases
+automatically.
+
+### Security
+
+The window runs with `contextIsolation: true`, `nodeIntegration: false` and `sandbox: true`.
+The renderer has no Node access and no socket. Everything goes through `contextBridge` in
+`electron/preload.ts`, which never passes `ipcRenderer` itself along. Otherwise the renderer
+could call any channel instead of only the actions we meant to expose.
+
+`src/index.html` sets a Content-Security-Policy that allows only the app's own scripts. Two
+consequences that fail silently if you forget them:
+
+- **The preload must be one self-contained file.** A sandboxed preload cannot load local
+  modules, so `electron:compile` bundles it with esbuild.
+- **`inlineCritical` is off** in the production build. It adds an inline `onload` handler to
+  the stylesheet, which the CSP blocks, and then part of the CSS is never applied.
+
+`npm run smoke` guards both.
+
+## License
+
+MIT, see [`LICENSE`](LICENSE).

package/bin/docker-desktop-mx.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/*
+ * Start de app vanuit npm: `npx @martijn-on-fhir/docker-desktop-mx`.
+ *
+ * Het pakket bevat de gebouwde app, geen Electron zelf; dat komt als peer-dependency mee met de
+ * installatie. `require('electron')` geeft in Node het pad naar het programma, en dat starten we
+ * met de map van dit pakket als app.
+ *
+ * `--from-npm` vertelt main dat dit geen ontwikkelversie is, ook al is de app niet verpakt:
+ * zonder die vlag noemt hij zich "(dev)" en gebruikt hij een eigen gebruikersmap.
+ */
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+let electron;
+
+try {
+  electron = require('electron');
+} catch {
+  // Engels: de taalinstelling van de app is hier nog niet te lezen, en Engels is de standaard.
+  console.error('Electron is missing. Reinstall the package, or add electron: npm install electron');
+  process.exit(1);
+}
+
+const child = spawn(electron, [path.join(__dirname, '..'), '--from-npm', ...process.argv.slice(2)], { stdio: 'inherit' });
+
+child.on('exit', (code, signal) => {
+  if (signal !== null) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});
+
+// Ctrl+C in de terminal hoort ook de app te sluiten, niet alleen dit script.
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => child.kill(signal));
+}