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

51 lines
2.8 KiB
Markdown

# 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.