Development

Run the app and its checks from source.

For everyday hosting, use deployment. This page is for contributors.

Run locally

Use Go 1.26 or newer for the backend and Node 24 or newer for browser builds and release tooling. The production image runs the Go binary without Node.

cd app
npm ci
npm run dev

Open http://localhost:3000. The development server rebuilds and restarts when source files change.

Node commands read your shell environment; they do not load app/.env. To enable local accounts:

export ACCOUNTS_DB=./data/accounts.sqlite
npm run dev

In PowerShell, use $env:ACCOUNTS_DB = './data/accounts.sqlite' instead of export.

Build a local container

From the repository root:

cp app/.env.example app/.env
docker compose -f app/compose.yaml up -d --build

Open http://localhost:3712. This setup reads app/.env and preserves accounts in a named volume.

Run checks

npm run check
npx playwright install chromium firefox webkit
npm run test:e2e
npm run test:e2e:platform

Command	Checks
npm run check	Lint, type checks, unit tests, and release tests
npm run test:e2e	Main browser suite
npm run test:e2e:platform	Chromium, Firefox, and WebKit smoke tests
npm run build	Build the Go binaries, compile browser TypeScript, and assemble assets
npm run test:go	Backend Go tests

Test commands build automatically. Release tests use mocked APIs and temporary repositories; they do not publish real releases.

Run npm commands from app/. Browser traces are saved under app/test-results/. Open one with npx playwright show-trace <path-to-trace.zip>.

Find the code

Directory	Contents
app/server/	Go HTTP, WebSockets, accounts, and relay
app/cmd/evakage/	Production server entry point
app/client/	Browser markup, styles, TypeScript, and assets
tests/	Unit, browser, and release tests
scripts/	Build, release, and benchmark scripts
deploy/	Published-image hosting
docs/	Mintlify documentation
maintainer/	Security review and measurements
app/dist/	Generated output; not committed

The backend builds to app/dist/evakage (app/dist/evakage.exe on Windows). Browser TypeScript builds produce JavaScript ES modules in app/dist/app/public/. The production Go module lives in app/. Go tests live in the separate tests/go/ module, which uses the local application through a replace directive. The protocol and browser suites run the Go backend through a test-only runner (tests/go/cmd/evakage-test/, built with the testbridge tag). Its authenticated control listener is absent from the production binary.

Documentation

The site is evakage.docs.thesteau.com. Navigation and branding live in docs/docs.json.

From docs/, run:

npx mint dev
npx mint validate
npx mint broken-links

See releases for publishing and contribution rules.