feat(launcher): install the server from a prebuilt archive (P1.3c)
The launcher is now a self-contained installer with install, run, update, doctor and uninstall. Install downloads waggle-server-<version>-<target> .tar.gz, checks its SHA-256, unpacks it into a per-user program directory and writes a waggle-server command that runs the tool on the archive's own Node. Nothing is built on the user's machine and the data directory stays WAGGLE_DATA_DIR or ~/.waggle. scripts/build-server-archive.mjs packs the staged desktop sidecar payload with the built web UI and a manifest. The download location waits for the repository decision; until then install takes --from or WAGGLE_RELEASE_BASE_URL (ADR-0009). Removes install.sh, scripts/waggle-server.sh and their CI job, which the installer replaces, and the bin name clash with @waggle/cli.
This commit is contained in:
49
docs/oss/adr/0009-installer-server-archive.md
Normal file
49
docs/oss/adr/0009-installer-server-archive.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# 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 must build the archive on each target system (P1.3d).
|
||||
- Windows cannot replace a running program: `update` and `uninstall` there run through `npx`,
|
||||
and the server must be stopped first.
|
||||
Reference in New Issue
Block a user