Files
waggle-os/docs/oss/adr/0009-installer-server-archive.md
shumeiko.it e0836388f1 docs: record the separate data directory (ADR-0011)
Add ADR-0011: the community edition defaults to ~/.waggle-community, a
temporary name that follows the product-name decision (Q8), and copies
nothing from the commercial ~/.waggle. It supersedes point 4 of
ADR-0009 and closes the pending "separate data directory" decision.

Update the install guide, troubleshooting, capabilities, memory,
architecture, the Windows build notes, THREAT_MODEL, README,
.env.example and the changelog. Log UF-068 (Open): marketplace skills
and plugins ignore a custom data directory.
2026-11-04 10:32:08 +01:00

2.8 KiB

ADR-0009: The installer delivers a prebuilt server archive

  • Status: Accepted; point 4 superseded by ADR-0011
  • 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.