@vex-chat/spire

@vex-chat/spire

Reference server implementation for the Vex protocol.

What's in the box

• REST API (Express 5) for full e2e messaging including auth, registration, users, servers, channels, invites, and file upload.

Install

Or clone the repo:

git clone [e-mail]:vex-protocol/spire-js
cd spire-js
npm ci

Running the server (Docker)

From a clone, with Docker and Docker Compose installed:

cp .env.example .env
# set SPK, JWT_SECRET, DB_TYPE, … (see Configuration)
docker compose up --build

Compose builds the image from this repo’s Dockerfile, starts Spire with a persistent spire-data volume mounted at /data (SQLite + files/, avatars/, emoji/), and fronts it with nginx on port 8080. Use http://localhost:8080 for HTTP and WebSocket.

Running without Docker

For local development or if you installed from npm, Spire runs with node --experimental-strip-types (no separate compile step):

npm start
# or: node --experimental-strip-types src/run.ts

From an npm install, sources live under node_modules/@vex-chat/spire/src/:

node --experimental-strip-types node_modules/@vex-chat/spire/src/run.ts

Configuration

Spire reads configuration from environment variables. Docker Compose: put them in a .env file next to docker-compose.yml (the env_file entry injects them into the container). Bare Node: dotenv loads .env from the process working directory when you run src/run.ts.

Required

Variable	Description
SPK	Server private key, hex-encoded. Generate with npm run gen-spk (prints SPK and JWT_SECRET lines). Used for server identity signing (NaCl).
JWT_SECRET	Hex or string used as the HMAC secret for JWTs — required and must be separate from SPK. npm run gen-spk emits a dedicated value; do not reuse SPK here.
DB_TYPE	sqlite, sqlite3, or sqlite3mem. All values use SQLite via better-sqlite3 (file or :memory:). sqlite3mem is for tests. The string mysql is still accepted for compatibility but maps to the same SQLite setup as the default (there is no MySQL driver).

Optional

Variable	Default	Description
API_PORT	16777	Port for the REST API and WebSocket server (see Spire default in code if unset).
NODE_ENV	(unset)	Set to production to disable interactive /docs / /async-docs. If unset or any other value, doc viewers are mounted. helmet() runs in all modes.
CORS_ORIGINS	(empty)	Comma-separated allowed Origin values for cors. If unset or empty, no cross-origin browser access (origin: false).
CANARY	(unset)

Sample .env

# Run `npm run gen-spk` and paste the two lines it prints (SPK + JWT_SECRET).
SPK=a1b2c3...
JWT_SECRET=d4e5f6...
DB_TYPE=sqlite
# CANARY=true
API_PORT=16777
NODE_ENV=production

Development

npm run build         # tsc (sanity check — runtime uses --experimental-strip-types)
npm run lint          # eslint strictTypeChecked
npm run lint:fix      # eslint --fix
npm run format        # prettier --write
npm run format:check
npm test              # vitest run
npx type-coverage     # type-coverage (≥95%)
npm run license:check # license allowlist gate

See AGENTS.md for the release flow (changesets → publish → deploy-hook) and the rules for writing changesets.

License

AGPL-3.0-or-later