Files
waggle-os/docs/oss/adr/0009-installer-server-archive.md
shumeiko.it 3a426a5423 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.
2026-11-01 01:35:54 +01:00

50 lines
2.7 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 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.