- serve the built client from the server via serve-static (CLIENT_DIR), falling back to index.html outside /api, /mcp, /docs and /health - replace server and client Dockerfiles and nginx with one root Dockerfile and a single liqa compose service on port 13000 - use Playwright's chromium-headless-shell with only its required libs and DejaVu/Liberation fonts instead of Debian chromium and Noto - clear the npm cache in the runtime image - bump version to 1.19.0
6.9 KiB
Development
Prerequisites
- Node.js 20+
- 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 chromium # first time only (server)
Copy .env.example to .env and fill in the required values before running.
Environment variables (server)
| Variable | Default | Description |
|---|---|---|
PORT |
3000 |
HTTP port |
KEYS_DIR |
keys |
Directory for key material used by credential/snippet workflows |
DB_PATH |
data/sessions.db |
SQLite database file |
SESSION_IDLE_TIMEOUT_MINUTES |
30 |
Idle timeout before open sessions are closed |
SESSION_DELETE_CLOSED_DAYS |
7 |
Retention period for closed sessions |
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 and proxies these API prefixes to localhost:13000 (or localhost:3000 when running server locally):
/environments/credentials/snippets/sessions/scenarios
Production build:
npm -w client run build
The built files are emitted to client/dist/.
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
Enable verbose NestJS log output during tests:
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.
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.
SQLite data is persisted in ./data/ and key files are mounted from ./keys/ — both directories are 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 environments, credentials, snippets, sessions, scenarios, and runs.
Tech stack
| Library | Purpose |
|---|---|
| React 19 + TypeScript | UI framework |
| Vite 6 | Dev server and bundler |
| react-router-dom (HashRouter) | Client-side routing |
| i18next + react-i18next | Internationalisation |
| lucide-react | Icon library |
| moment | Relative timestamp formatting |
| ESLint 10 + Prettier | Linting and formatting |
| Storybook 10 + Vitest | Component development and testing |
Directory layout
client/
src/
api/ API client modules (environments, credentials, snippets, sessions, scenarios)
hooks/ useTheme (light/dark persistence)
i18n/ i18next bootstrap + locales/en.json
pages/ Environment/Credential/Snippet/Session/Scenario/Run pages
ui/ Reusable component library
Badge, Breadcrumbs, Button, Card, Input, Select,
SidePanel, Table, ThemeSwitcher, Timestamp
.storybook/
stories/ *.stories.tsx for all ui/ components
Routing
Hash-based routing (/#/path) avoids conflicts with the Vite dev-server proxy. Default route redirects to /#/scenarios.
| Route | Page |
|---|---|
/#/environments |
Environment list |
/#/credentials |
Credential list |
/#/snippets |
Snippet list |
/#/sessions |
Session list |
/#/scenarios |
Scenario list |
/#/runs |
Cross-scenario runs list |
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.