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

2.7 KiB

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.