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.
131 lines
5.3 KiB
Markdown
131 lines
5.3 KiB
Markdown
# Building the Windows desktop app
|
|
|
|
How to build the Waggle desktop installer for Windows from the `oss/community-edition`
|
|
branch. The build has to run on Windows: the packaging scripts take the bundled Node.js
|
|
runtime and the native modules (better-sqlite3, onnxruntime) from the machine they run on,
|
|
so a build made on macOS would ship macOS binaries.
|
|
|
|
The release workflow (`.github/workflows/release.yml`) runs the same build on GitHub's
|
|
`windows-latest` runner for every `v*` tag and for pull requests that touch the desktop app.
|
|
It has not run yet; the first build is part of the week 3 acceptance. Record what fails in
|
|
`docs/oss/upstream-fixes.md` or `docs/oss/baseline.md`.
|
|
|
|
## 1. Prepare the machine
|
|
|
|
- Windows 10 or 11, x64, with about 20 GB of free disk space.
|
|
- [Git for Windows](https://git-scm.com/download/win).
|
|
- [Node.js 22](https://nodejs.org/en/download), x64. Use 22.23.2 if you can: the installer
|
|
bundles exactly this version, CI uses it, and the build checks that the bundled runtime can
|
|
load the native modules installed by your Node.
|
|
- [Rust](https://rustup.rs) through rustup, stable 1.94 or newer, with the default host
|
|
`x86_64-pc-windows-msvc`.
|
|
- [Visual Studio 2022 Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
|
|
with the **Desktop development with C++** workload (MSVC and the Windows SDK). Rust links
|
|
with it, and npm uses it if a native module has to be compiled.
|
|
- WebView2 Runtime. It ships with current Windows 10 and 11.
|
|
|
|
Run every command below in **PowerShell**, not Git Bash. The build unpacks the Node.js zip
|
|
with `tar`; Windows' own `tar` reads zip files, the GNU `tar` in Git Bash does not.
|
|
|
|
Check the tools:
|
|
|
|
```powershell
|
|
node --version # v22.x
|
|
rustc --version # 1.94 or newer
|
|
cargo --version
|
|
git --version
|
|
```
|
|
|
|
## 2. Get the code
|
|
|
|
The branch is not on a shared remote, so copy it as a git bundle. On the machine that has
|
|
the repository:
|
|
|
|
```bash
|
|
git bundle create waggle-oss.bundle oss/community-edition
|
|
```
|
|
|
|
The bundle holds the full history, including the leaked Stripe secret (UF-005). Copy it to
|
|
the Windows machine directly and do not upload it anywhere.
|
|
|
|
On Windows, clone into a short path; `node_modules` and the Rust `target` folder produce
|
|
long paths:
|
|
|
|
```powershell
|
|
git clone --branch oss/community-edition C:\path\to\waggle-oss.bundle C:\w\waggle-os
|
|
```
|
|
|
|
To update later, make a new bundle and pull from it:
|
|
|
|
```powershell
|
|
git -C C:\w\waggle-os pull C:\path\to\waggle-oss.bundle oss/community-edition
|
|
```
|
|
|
|
## 3. Build
|
|
|
|
```powershell
|
|
cd C:\w\waggle-os
|
|
npm ci
|
|
cd app
|
|
npm ci
|
|
npm run tauri:build:win -- --bundles nsis
|
|
```
|
|
|
|
`tauri:build:win` downloads and verifies the Node.js 22.23.2 runtime, bundles the sidecar,
|
|
copies the native modules, builds the web UI and then the Tauri shell. The first run compiles
|
|
the Rust shell from scratch and takes much longer than later runs.
|
|
|
|
`--bundles nsis` builds only the NSIS installer, the one the app is configured for (a
|
|
per-user install without administrator rights). Without the flag Tauri also builds an MSI,
|
|
for which it downloads WiX; the release workflow builds both (`--bundles nsis,msi`).
|
|
|
|
The installer:
|
|
|
|
```
|
|
app\src-tauri\target\x86_64-pc-windows-msvc\release\bundle\nsis\Waggle_1.0.0_x64-setup.exe
|
|
```
|
|
|
|
The same staged files make the server archive that the installer tool
|
|
(`packages/launcher`) installs. To build it and run the release workflow's smoke tests:
|
|
|
|
```powershell
|
|
cd C:\w\waggle-os
|
|
npm run build --workspace @waggle-ai/waggle
|
|
node scripts/build-server-archive.mjs
|
|
node scripts/release-smoke.mjs installer
|
|
```
|
|
|
|
The archive is `artifacts\waggle-server-<version>-windows-x64.tar.gz`. The installer test
|
|
installs it into a temporary folder, runs `doctor`, starts the server on a free port and
|
|
uninstalls it.
|
|
|
|
After installing the app (section 4), the desktop test starts it, waits until its sidecar
|
|
answers on port 3333, then stops both. Close Waggle first so the port is free:
|
|
|
|
```powershell
|
|
node scripts/release-smoke.mjs desktop --app "$env:LOCALAPPDATA\Waggle\waggle.exe"
|
|
```
|
|
|
|
## 4. Check the result
|
|
|
|
1. Run the installer. It is not signed, so SmartScreen shows "Windows protected your PC":
|
|
choose **More info**, then **Run anyway**. Waggle installs for the current user.
|
|
2. Start Waggle from the Start menu. The window should move past "Starting Waggle…" to the
|
|
Home screen.
|
|
3. If it stays on "Starting Waggle…", close it and take the log from
|
|
`%USERPROFILE%\.waggle-community\logs\service.log`.
|
|
4. Chat needs a model: an API key in Settings → Models (Provider Keys), or a running Ollama.
|
|
|
|
Waggle keeps its data in `%USERPROFILE%\.waggle-community`.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
|---|---|
|
|
| `link.exe` not found, or a Rust linker error | Install the **Desktop development with C++** workload of the Build Tools. |
|
|
| `npm ci` compiles better-sqlite3 and fails | The prebuilt binary could not be downloaded. Check the network or proxy; compiling it needs the C++ workload and Python 3. |
|
|
| `[bundle-node]` reports an ABI or architecture mismatch | The Node.js you build with is not 22.x x64. Install 22.23.2. |
|
|
| `tar` cannot open the Node.js archive | The build ran in Git Bash. Use PowerShell. |
|
|
| Errors about paths that are too long | Clone to a shorter folder such as `C:\w\waggle-os`. |
|
|
| Files in `target` are locked during the build | Antivirus is scanning them. Run the build again, or exclude the folder. |
|