Phaset API

Phaset API is the backend for Phaset. It handles authentication, organizations and tenants, catalog records, standards, reviews, assurance obligations, SCIM, SSO, access tokens, health scores, engineering metrics, and webhook ingestion.

Quick Start

Install dependencies:

npm install

Create phaset.config.json in the project root. You can start from phaset.config.example.json.

cp phaset.config.example.json phaset.config.json

Run the API:

npm start

The API listens on http://0.0.0.0:3000 by default. Use HOST and PORT, or the server.host and server.port config values, to change that.

Main Commands

• npm start: run the local development server with tsx.
• npm run lint: run Biome without writing changes.
• npm run lint:fix: run Biome and apply safe formatting fixes.
• npm test: run type coverage and unit tests.
• npm run build: bundle the API to lib/phaset_api.mjs.
• npm run verify: run lint, tests, and build.
• npm run docs: generate Typedoc output and a dependency graph.
• npm run release: create versioned and latest zip archives.
• npm run build:docker: build the GHCR Docker image locally.
• npm run push:docker: push the versioned and latest GHCR Docker tags.

Generating the dependency graph requires Graphviz:

brew install graphviz

Configuration

Configuration can come from a config file, CLI flags, or environment variables. The default config file path is ./phaset.config.json. Packaged and container deployments can set PHASET_CONFIG_FILE to point at a mounted config file.

Required production values:

Variable	Config Path	Description
EMAIL_USER	email.user	SMTP username
EMAIL_PASSWORD	email.password	SMTP password
EMAIL_HOST	email.host	SMTP host
AUTH_JWT_SECRET	auth.jwtSecret	JWT signing secret
APP_URL	auth.appUrl	Frontend app URL
BOOTSTRAP_ORG_NAME	phaset.bootstrap.organizationName	Initial organization name
BOOTSTRAP_ADMIN_EMAIL	phaset.bootstrap.adminEmail	Initial admin email
STORAGE_KEY	storage.encryptionKey	Database encryption key

Common optional values:

Variable	Default	Description
PORT	3000	Server port
HOST	0.0.0.0	Server bind host
DATA_DIR	./	Root directory for phaset_auth_db and phaset_data_db
ALLOWED_DOMAINS	local Vite origins	Comma-separated CORS origins
EMAIL_PORT	587	SMTP port
EMAIL_SECURE	true	Set to false for non-TLS SMTP
DEBUG	false	Enable debug logging

SSO can be enabled with SSO_ENABLED=true. Supported providers are azure and google; see phaset.config.example.json for the full shape.

Docker

Build the image:

npm run build:docker

Run with a mounted config file and persistent data volume:

docker run -d \
  -v "$(pwd)/phaset.config.json:/app/phaset.config.json:ro" \
  -v phaset-data:/app/data \
  -p 3000:3000 \
  --name phaset-api \
  ghcr.io/phasetdev/phaset-api:latest

Docker Compose:

services:
  phaset-api:
    image: ghcr.io/phasetdev/phaset-api:latest
    ports:
      - "3000:3000"
    environment:
      PHASET_CONFIG_FILE: /app/phaset.config.json
      DATA_DIR: /app/data
    volumes:
      - ./phaset.config.json:/app/phaset.config.json:ro
      - phaset-data:/app/data
    restart: unless-stopped

volumes:
  phaset-data:

Distribution

npm run release builds the API, creates VERSION, generates SBOM and OSS license artifacts, copies the Dockerfile and example config, and writes:

• phaset_api_<version>.zip
• phaset_api_latest.zip

The release folder is self-contained for the bundled runtime. Mount or provide phaset.config.json separately when running it.

API Docs

OpenAPI schemas live in api/. Generated code documentation is created with:

npm run docs

License

MIT