110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# Operations guide
|
|
|
|
## Prerequisites
|
|
|
|
Ubuntu GNOME 24.04 or newer, the packaged Bare runtime, PipeWire/WirePlumber,
|
|
GNOME desktop portals, GTK4/libadwaita, AT-SPI2, and a QVAC-visible GPU are
|
|
required for the full runtime. Node.js is a build and test dependency only.
|
|
See [hardware compatibility](hardware-compatibility.md).
|
|
|
|
## Web installation
|
|
|
|
For the current Gitea rolling build:
|
|
|
|
~~~bash
|
|
curl -fsSL https://git.ssh.surf/snxraven/gnome-jarvis/raw/branch/main/packaging/web-installer.sh | bash -s -- --enable
|
|
~~~
|
|
|
|
The installer downloads the self-contained Bare bundle from the `rolling`
|
|
release and delegates to the repository installer. Re-running it replaces the
|
|
previous user-local application and extension trees after stopping
|
|
`jarvisd.service`; config and data stay in place. Omit `--enable` to copy
|
|
files without starting the service unless the daemon was already running.
|
|
Use `JARVIS_SERVER`, `JARVIS_REPO`, and `JARVIS_BUNDLE_URL` for a mirror.
|
|
|
|
## Development start
|
|
|
|
```bash
|
|
npm ci
|
|
npm test
|
|
npm run gpu-doctor
|
|
npm run cu-doctor
|
|
npm run voice-doctor
|
|
bash packaging/bare-launch.sh daemon/bare-entry.js
|
|
```
|
|
|
|
`packaging/bare-launch.sh` selects the vendored Bare binary and is the same
|
|
wrapper the packaged service uses. Do not reload the daemon with
|
|
`node --watch`; Bare is the production loop.
|
|
|
|
Use `npm run qvac:serve:diagnostic` only when a separate local client needs the
|
|
OpenAI-compatible endpoint. Keep its host at `127.0.0.1`.
|
|
|
|
## User service
|
|
|
|
```bash
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now jarvisd.service
|
|
systemctl --user status jarvisd.service
|
|
journalctl --user -u jarvisd.service -f
|
|
```
|
|
|
|
The unit at `packaging/jarvisd.service` (installed to
|
|
`~/.config/systemd/user/jarvisd.service`) starts Bare on
|
|
`daemon/bare-entry.js` with working directory `~/.local/share/jarvis-qvac` and
|
|
`QVAC_CONFIG_PATH=~/.config/jarvis/qvac.config.json`. The repository
|
|
development unit uses the checkout path; use the packaged unit when testing
|
|
installation behavior.
|
|
|
|
Restart after daemon code changes:
|
|
|
|
```bash
|
|
systemctl --user restart jarvisd.service
|
|
```
|
|
|
|
## Desktop launcher
|
|
|
|
`packaging/install.sh` writes:
|
|
|
|
- `~/.local/share/applications/io.qvac.Jarvis.Control.desktop`
|
|
- `~/.local/share/icons/hicolor/scalable/apps/io.qvac.Jarvis.Control.svg`
|
|
|
|
The **Jarvis** launcher opens Control Center (`gjs -m …/apps/control-center/main.js`).
|
|
See [brand](brand.md) and [settings](settings.md).
|
|
|
|
## Extension development
|
|
|
|
```bash
|
|
gnome-extensions enable [email protected]
|
|
dbus-run-session -- gnome-shell --nested --wayland
|
|
```
|
|
|
|
Keep inference and long-running work in `jarvisd`. Live HUD files are
|
|
`~/.local/share/gnome-shell/extensions/[email protected]`. Copy the checkout
|
|
tree there, then reload the extension.
|
|
|
|
GNOME 50 does not implement `ReloadExtension`. Calling
|
|
`org.gnome.Shell.Extensions.ReloadExtension` on the standalone Extensions
|
|
helper can also hit a stale cache. After copying files:
|
|
|
|
1. Disable then enable on the real Shell (`org.gnome.Shell` at
|
|
`/org/gnome/Shell`), or
|
|
2. Log out and back in.
|
|
|
|
A stylesheet or JS parse error (for example St CSS `errcode:15`) will not
|
|
hot-reload until that disable/enable or a new session. See
|
|
[troubleshooting](troubleshooting.md).
|
|
|
|
## State and storage
|
|
|
|
| Location | Contents | Default retention |
|
|
| --- | --- | --- |
|
|
| `~/.local/share/jarvis/memory` | harness memory and RAG data | user-managed |
|
|
| `~/.local/share/jarvis/voices` | local voice references | user-managed |
|
|
| `~/.local/share/jarvis/audit` | CU action metadata and hashes | user-managed |
|
|
| `~/.cache/jarvis` | models, jobs, temporary CU state | disposable |
|
|
| `~/Jarvis` | generated media and transcripts | user-managed |
|
|
|
|
Use the uninstall script with `--yes`; add `--purge-data` only to remove the
|
|
listed Jarvis-owned data locations.
|