The architecture guide, AGENTS.md and the threat model said releases were built by hand or Windows-first; ADR-0009 still listed the release workflow as future work. The Windows build guide named the missing Settings > API Keys tab.
51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# ADR-0009: The installer delivers a prebuilt server archive
|
|
|
|
- Status: Accepted
|
|
- Date: 2026-11-01
|
|
|
|
## Context
|
|
|
|
The scope requires a Node-based install tool without Docker or Python (fixed decision 4), built
|
|
on `packages/launcher` (P1.3c). Two install paths existed:
|
|
|
|
- `npx @waggle-ai/waggle` started the server from npm. npm installed the server dependencies on
|
|
the user's Node, so native modules could fall back to node-gyp, and the CUDA and Puppeteer
|
|
download skips could not be set (ADR-0005, ADR-0008). The tool did not serve the web UI.
|
|
- `install.sh` cloned the repository and built it on the user's machine. It needed git, npm and,
|
|
for some prebuild mismatches, a compiler. It ran on Linux and macOS only.
|
|
|
|
The desktop build already stages a complete sidecar payload: `service.js`, the pinned Node, the
|
|
native modules and the production `node_modules` (ADR-0008).
|
|
|
|
## Decision
|
|
|
|
1. **The release publishes one server archive per target**: `windows-x64`, `macos-arm64`,
|
|
`macos-x64` and `linux-x64`. `scripts/build-server-archive.mjs` packs the staged desktop
|
|
payload, the built web UI under `web/` and a `manifest.json` into
|
|
`waggle-server-<version>-<target>.tar.gz`, with a `.sha256` next to it.
|
|
2. **The installer downloads and unpacks it.** `packages/launcher` is now a self-contained tool
|
|
(`waggle-server`) that uses only Node's built-in modules:
|
|
- `install` downloads the archive for this system, checks its SHA-256 and unpacks it into a
|
|
per-user program directory, then writes a `waggle-server` command;
|
|
- `run` (the default) starts the server on the archive's own Node and opens the browser;
|
|
- `doctor` checks the runtime, SQLite, the data directory, the port and the command;
|
|
- `update` swaps in another version; `uninstall` removes the program and keeps the data.
|
|
3. **Nothing is built on the user's machine.** The archive carries its own Node, so the user's
|
|
Node (20 or newer) is needed only for the first `npx` call.
|
|
4. **The data directory does not change**: `WAGGLE_DATA_DIR` or `~/.waggle`, as for the sidecar.
|
|
5. **The download location waits for the repository decision (Q9).** Until then `install` takes
|
|
`--from <path or URL>`, and `WAGGLE_RELEASE_BASE_URL` points it at a mirror.
|
|
|
|
The project owner chose this over publishing the server to npm on 2026-11-01.
|
|
|
|
## Consequences
|
|
|
|
- The installed server runs exactly the payload the desktop app ships and the release smoke
|
|
tests.
|
|
- An archive is about 130 MB (macOS arm64); it is downloaded once per version.
|
|
- `install.sh`, `scripts/waggle-server.sh` and their CI job are removed.
|
|
- The release workflow (`release.yml`) builds the archive on each target system and
|
|
smoke-tests the installer against it.
|
|
- Windows cannot replace a running program: `update` and `uninstall` there run through `npx`,
|
|
and the server must be stopped first.
|