Reference

Build from source

How to build and run Rowkery from its source code, make your own disk image, run the tests, and build these docs and the website. Rowkery is open source under the Apache License 2.0.

What you need

For the tests that use Postgres you also need Docker, or any Postgres 16 you can connect to.

Run it

git clone https://github.com/rowkery/rowkery.git
cd rowkery

cd apps/rowkery-tauri
npm install

npm run tauri dev

A build you make yourself doesn't update itself, and its Report an Issue sheet can only copy a report: sending needs the address of the report service, set at build time as VITE_ROWKERY_REPORT_URL in apps/rowkery-tauri/.env.

Run a branch or a pull request

From the repository's root:

make dev                  # the current branch
make dev feat/some-thing  # that branch
make dev 35               # pull request #35

make dev fetches the branch from GitHub, resets your local copy of it to match, runs npm install when the package lock changed since the last install, then starts the app with npm run tauri dev. It runs as Rowkery Dev, which keeps its own settings, saved connections and keychain items, so a branch you try never sees the connections in your installed Rowkery. It stops without changing anything if you have uncommitted changes to tracked files.

Make a disk image

make dmg            # for this Mac's chip
make dmg universal  # one image for Apple Silicon and Intel Macs

The disk image ends up in target/release/bundle/dmg/ (or target/universal-apple-darwin/release/bundle/dmg/ for a universal one), and Finder shows it when the build is done. make dmg universal adds the two Rust targets it needs first.

The app in it isn't signed, so on another Mac, macOS blocks it the first time. After dragging it to Applications, run this once on that Mac, or use Open Anyway in System Settings › Privacy & Security:

xattr -dr com.apple.quarantine /Applications/Rowkery.app

make release builds the public release (a universal disk image, the signed update and its feed). It needs the Rowkery team's update signing key, so it's only for maintainers.

Linux and Windows

Rowkery builds on Linux and Windows, but those builds are unofficial and aren't tested the way the Mac app is. On both, Rowkery draws its own window controls; Use system window controls (next launch) in ⌘K (Ctrl+K there) switches to the system's.

On Linux, install WebKitGTK 4.1 and GTK 3 with the other Tauri prerequisites. On Debian or Ubuntu:

sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev \
  libayatana-appindicator3-dev librsvg2-dev patchelf

To run the real app without a display, as in a container, use Xvfb and set WEBKIT_DISABLE_DMABUF_RENDERER=1.

Without a secret service (such as GNOME Keyring) running, Rowkery keeps passwords in its encrypted fallback file. Its folder is ~/.config/rowkery on Linux and %APPDATA%\Rowkery on Windows.

Run the tests

Before you push a change, run the whole set from the repository's root:

cd apps/rowkery-tauri && npm run typecheck && npx vitest run
cd ../..
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

These run on your machine only: the GitHub Actions workflows in the repository are started by hand, never by a push or a pull request.

The test Postgres

The Postgres integration tests need a test database. The repository's Compose file starts one on port 54329, with user, database and password all rowkery:

docker compose -f docker-compose.test.yml up -d postgres
export ROWKERY_PG_HOST=127.0.0.1 ROWKERY_PG_PORT=54329 ROWKERY_PG_PASSWORD=rowkery
cargo test --workspace --features rowkery-core/postgres-integration,rowkery-mcp/postgres-integration

One test switches a window to a second database; create it once with psql -h 127.0.0.1 -p 54329 -U rowkery -c "CREATE DATABASE orders".

Set ROWKERY_CONFIG_DIR to a temporary folder when you run the tests or the app against it, so they leave your own connections and keychain alone.

Browser proofs

Every change to the interface comes with a browser proof: a script in scripts/ that serves the interface with Vite, stands in for the Rust core, drives it in headless Chromium and checks what's on screen. Each script's first lines say what it proves.

cd apps/rowkery-tauri
npx playwright install chromium
npx vite --port 1420 &
cd ../..
NODE_PATH=apps/rowkery-tauri/node_modules node scripts/toast-browser-proof.mjs

Latency budgets

Rowkery has a time budget for each step on the hot path, such as 16 ms to open ⌘K and 66 ms from ⌘↵ to the first rows on screen on a local database. They're in scripts/budgets.json. A change to the Rust code or the results path runs scripts/latency-browser-proof.mjs and, on a Mac, scripts/latency-proof.sh against the test Postgres, which fail a run that's much slower than the reference.

The docs and the website

make docs   # builds these docs and serves them on http://localhost:3001
make web    # builds rowkery.com and serves it on http://localhost:3000

Both are static sites made with Next.js, in apps/docs and apps/web. For the docs with hot reload, run npm install and npm run dev in apps/docs.

Contributing

Contributions are welcome. CONTRIBUTING.md covers how branches, commits and pull requests are shaped, the checks a change has to pass, and how to describe what you changed. The code of conduct, the design system (DESIGN.md) and the product spec (docs/spec.md) are in the same repository at github.com/rowkery/rowkery.

Questions and ideas go in Discussions, and bugs in Issues. For a security problem, see Report a vulnerability.