bunfork
Documentation menu

Getting started

Go from a clean checkout to the native server in five commands. Static exports have a shorter, secret-free path below.

Run the native application

  1. Build the pinned source

    cargo build --release --locked

    Bunfork requires Rust 1.89 or newer (edition 2024) on the stable toolchain. SQLCipher and OpenSSL are bundled by the database dependency.

  2. Create two different secrets

    ./target/release/bunfork keygen
./target/release/bunfork keygen --out .bunfork.token

    Each file contains a private 256-bit secret. The decoded database key and API token must differ; case-only hex variations are rejected as equal.

  3. Apply the embedded migration

    ./target/release/bunfork migrate

    The database is created at data/bunfork.db by default. Migrations run transactionally, then the exact schema and ledger are validated.

  4. Start development mode

    ./target/release/bunfork dev

    The default listener is 0.0.0.0:3100. Native templates and routes are rescanned per request; this is server reload, not browser HMR.

  5. Probe readiness

    curl --fail http://localhost:3100/api/health
curl --fail http://localhost:3100/_bunfork/ready

    Health identifies the service, package version, and whole-second uptime. Readiness returns {"message":"ok"}; in native mode it also checks the open encrypted database. Both endpoints are intentionally public.

Serve a static export without secrets

Static mode never opens SQLCipher and does not read the database key, API token, tenant, or model. First build the browser artifact with its own toolchain, then:

./target/release/bunfork admit \
  --artifact frontend/dist \
  --manifest bunfork-static.json \
  --mode spa \
  --fallback index.html \
  --trailing-slash ignore

./target/release/bunfork doctor \
  --static frontend/dist \
  --manifest bunfork-static.json

./target/release/bunfork serve \
  --static frontend/dist \
  --manifest bunfork-static.json

Use the SPA settings only when the client router requires an explicit index.html fallback. Prerendered multi-page exports should use MPA mode.

Override state explicitly

./target/release/bunfork \
  --database "$HOME/.local/share/bunfork/bunfork.db" \
  --key-file "$HOME/.config/bunfork/db.key" \
  --tenant acme \
  --model notes \
  serve --token-file "$HOME/.config/bunfork/api.token"

Global data options must precede the command. Their environment equivalents are BUNFORK_DB, BUNFORK_KEY_FILE, BUNFORK_TENANT, and BUNFORK_MODEL.