- install production dependencies and chromium in a separate stage - drop source maps, typescript sources and declarations, docs, typeorm's browser build, better-sqlite3's c sources and ffmpeg - base the runtime on debian:bookworm-slim with only the node binary - document the image layout - bump version to 1.22.1
11 KiB
Development
Prerequisites
- Node.js 24+ (required by
enginesinpackage.json; the Docker image uses Node.js 24) - Docker + Docker Compose
The repository is a npm workspace monorepo with two packages:
| Workspace | Directory | Description |
|---|---|---|
server |
server/ |
NestJS API + MCP server |
client |
client/ |
React 19 + Vite admin UI |
Install all dependencies from the repo root:
npm install
npx playwright install --only-shell chromium # first time only: headless Chromium for the server
No .env is needed: every setting below has a default. To override settings, copy .env.example to .env and uncomment the ones you need. Docker Compose loads .env when it exists.
Environment variables (server)
All settings are validated at startup by server/src/config/app.config.ts.
| Variable | Default | Description |
|---|---|---|
NODE_ENV |
development |
production in the Docker image. Shown in the startup log, and selects the default CORS origins |
CORS_ORIGINS |
(empty) | Comma-separated origins allowed to call the API cross-origin. When empty: the Vite dev server (http://localhost:5173, http://127.0.0.1:5173) unless NODE_ENV=production, then the compose port (http://localhost:13000, http://127.0.0.1:13000) |
PORT |
3000 |
HTTP port |
DB_PATH |
data/liqa.db |
SQLite database file |
FILES_DIR |
data/files |
Where scenario files and run artifacts are stored |
FILE_RUN_EXPIRATION_DAYS |
7 |
How long run artifacts (downloads, failure dumps, traces) are kept |
FILE_CLEANUP_CRON |
0 3 * * * |
When expired files are deleted |
SESSION_IDLE_TIMEOUT_MINUTES |
30 |
Idle timeout before open sessions are closed |
SESSION_DELETE_CLOSED_DAYS |
7 |
Retention period for closed sessions |
PLAYWRIGHT_TRACE_MODE |
off |
Default Playwright trace mode for runs: on, retain-on-failure or off (see scenario.md) |
CLIENT_DIR |
(empty) | Directory with the built client to serve at / (the Docker image sets it to client); empty means the server doesn't serve the UI |
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH |
(Playwright default) | Path to a Chromium binary to use instead of Playwright's own. Not set in Docker: the image ships Playwright's chromium-headless-shell (matching the Playwright version) under PLAYWRIGHT_BROWSERS_PATH=/ms-playwright. |
Starting the application
Server
Development (watch mode, restarts on file changes):
npm -w server run start:dev
Production build, then start:
npm -w server run build
npm -w server run start:prod
The server listens on port 3000 by default.
Client
Development (Vite dev server with HMR):
npm -w client run dev
The Vite dev server runs on http://localhost:5173. It has no API proxy: the client calls VITE_API_URL (default /api/v1 on its own origin), and the server allows CORS from http://localhost:5173. So point it at a running server:
npm -w client run dev:compose-api # API of the compose container (localhost:13000)
VITE_API_URL=http://localhost:3000/api/v1 npm -w client run dev # API of a locally started server
Production build:
npm -w client run build
The built files are emitted to client/dist/.
Database migrations
The SQLite schema is managed by TypeORM migrations in server/src/database/migrations/; synchronize is off.
-
Docker: the container applies pending migrations before starting the server.
-
Locally: build, then apply them before starting the server (it refuses to start while migrations are pending):
npm -w server run build npm -w server run migration:run # apply pending migrations to DB_PATH npm -w server run migration:show # list migrations and whether they're applied
The scripts run from server/, so DB_PATH (default data/liqa.db) is relative to it, and they read server/.env if present, like the server does.
Changing the schema (adding or changing an entity):
-
Change the entity and build (
npm -w server run build). -
Make sure your local database is on the latest migration (
migration:run). -
Generate a migration from the difference between the entities and that database:
npm -w server run migration:generate -- src/database/migrations/AddSomething -
Review the generated file, then add its class to
MIGRATIONSinsrc/database/migrations/index.ts(they're listed explicitly, oldest first). -
Run the tests:
test/migrations.spec.tschecks that the migrations produce exactly the schema the entities describe, and fails if an entity change has no migration.
The initial migration (Initial…) adopts databases created before migrations existed (by synchronize): if the tables already exist, it's only recorded as applied.
Running tests
Server (Jest)
npm -w server run test
Run a single spec file:
npm -w server run test -- --no-coverage test/scenario.controller.spec.ts
Watch mode:
npm -w server run test:watch
Print the NestJS logs of the test app (they're silenced by default; DEBUG=test):
npm -w server run test:debug
Client (Vitest + Storybook)
Storybook interaction tests (runs all *.stories.tsx files):
npm -w client run test:storybook
Launch Storybook dev server (with live preview):
npm -w client run storybook
Formatting code
Both workspaces use Prettier.
Server — rewrites src/**/*.ts and test/**/*.ts:
npm -w server run format
Client — rewrites src/**/*.{ts,tsx} and .storybook/**/*.{ts,tsx}:
npm -w client run format
Linting
Both workspaces use ESLint with typescript-eslint. The client also includes eslint-plugin-react-hooks and eslint-plugin-react-refresh.
Server:
npm -w server run lint # report issues
npm -w server run lint:fix # report and auto-fix
Client:
npm -w client run lint # report issues
npm -w client run lint:fix # report and auto-fix
Both workspaces target zero errors. Run lint before committing.
Building the container
The root Dockerfile builds a single image with the whole application: it builds the client and the server in separate stages, and the runtime image runs the server, which also serves the built client (CLIENT_DIR).
The runtime image uses Playwright's headless-only Chromium build (chromium-headless-shell) with just the shared libraries it links against, plus DejaVu and Liberation fonts (Liberation is metric-compatible with Arial/Times, so pages lay out as they would with those fonts). All browser launches are headless, so the full desktop Chromium isn't installed. If a new Playwright version needs another library, ldd on the chrome-headless-shell binary in the image lists what's missing.
To keep the image small, production dependencies and the browser are installed in a separate runtime-deps stage, which drops what nothing loads at runtime (source maps, TypeScript sources and declarations, docs, TypeORM's browser build, better-sqlite3's C sources, and Playwright's ffmpeg, which is only used for video recording). The runtime stage is plain debian:bookworm-slim with only the node binary copied in, so the image has no npm, npx, yarn or corepack. If a package starts failing in the image only, check whether it reads one of the deleted file types at runtime.
docker compose build
To rebuild without the layer cache:
docker compose build --no-cache
Running with Docker Compose
Start (detached):
docker compose up -d
Build and start in one step:
docker compose up -d --build
Everything is served by the single liqa container at http://localhost:13000: the UI at /, the REST API at /api/v1, MCP at /mcp, Swagger at /docs and health at /health. Unknown paths outside those routes get the client's index.html, so client-side routes survive a page refresh.
When switching from the old two-container setup (server + client), remove the old containers with docker compose up -d --build --remove-orphans.
The SQLite database and stored files are persisted in ./data/, which is volume-mounted into the container.
Stop and remove containers:
docker compose down
View logs:
docker compose logs -f
Client overview
The client (client/) is a React 19 + TypeScript SPA built with Vite. It provides a browser UI for managing scenarios, runs, snippets, credentials, environments and sessions, and for importing exported YAML.
Tech stack
| Library | Purpose |
|---|---|
| React 19 + TypeScript | UI framework |
| Vite 6 | Dev server and bundler |
react-router-dom 7 (BrowserRouter) |
Client-side routing |
| @tanstack/react-query | Data fetching (cross-scenario runs list) |
| i18next + react-i18next | Internationalisation |
| lucide-react | Icon library |
| @monaco-editor/react | Code editor for steps and snippets |
| react-markdown + highlight.js | Markdown descriptions and code highlighting |
| yaml | YAML export of entities |
| moment | Relative timestamp formatting |
| ESLint 10 + Prettier | Linting and formatting |
| Storybook 10 + Vitest | Component development and testing |
Directory layout
client/
src/
api/ API client (client.ts) and types (types.ts)
components/ modals/ - run, export, export logs and delete confirmation modals
hooks/ useTheme, usePageTitle, useRunDefaults, useImportFile
i18n/ i18next bootstrap + locales/en.json
lib/ highlight.js setup, API error toast events
pages/ scenario/, run/, snippet/, credential/, environment/, session/, import/
ui/ Reusable component library (Badge, Button, Card, CodeEditor, Modal,
Select, SidePanel, Table, Toast, ... - see ui/index.ts)
.storybook/
stories/ *.stories.tsx for ui/ components
Routing
BrowserRouter with plain paths. The root and unknown paths redirect to /scenarios. The server answers these paths with the client's index.html (see architecture.md), so they work on refresh.
| Route | Page |
|---|---|
/scenarios |
Scenario list |
/scenarios/:id |
Scenario details (steps, versions, credentials, used snippets, files) |
/scenarios/:id/runs, /scenarios/:id/runs/:runId |
Runs of a scenario, run details |
/runs |
Cross-scenario runs list |
/snippets, /credentials, /environments, /sessions |
Entity lists (plus /:id, /new, /:id/edit where applicable) |
/import |
Central import |
Theming
Light/dark theme is toggled by the ThemeSwitcher button in the sidebar footer. The selection is persisted to localStorage and applied as data-theme on <html> before React mounts (anti-FOUC inline script in index.html).
The sidebar footer also shows the app version read from the workspace root package.json and injected via Vite define.