Files
liqa/docs/development.md
T
ars9 a4bfa3117f feat(docker): serve the whole app from a single container
- 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
2026-09-30 20:28:10 +03:00

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.