docs: bring docs up to date and drop unused keys setting

- rewrite architecture, development, mcp and scenario docs to match the
  current code: single container, all mcp tools, runs, versioning,
  timeouts, settings, client routing and dev setup
- rewrite README as a general overview without liquio-specific wording
- remove the unused KEYS_DIR setting and ./keys compose mount
- remove the unused result parameter from step code execution
- complete .env.example with the file storage settings and fix the
  DB_PATH default
This commit is contained in:
Andrii Arsenin committed 2026-09-30 21:18:41 +03:00
1 parent 0d621a8bdb
commit 522c49d7c2
12 files changed
+239 -207

No files matched your search

+37 -27
View File
@@ -16,20 +16,26 @@ Install all dependencies from the repo root:
```bash
npm install
npx playwright install chromium # first time only (server)
npx playwright install --only-shell chromium # first time only: headless Chromium for the server
```
Copy `.env.example` to `.env` and fill in the required values before running.
### Environment variables (server)
All settings are validated at startup by `server/src/config/app.config.ts`.
| Variable | Default | Description |
|---|---|---|
| `NODE_ENV` | `development` | Shown in the startup log |
| `PORT` | `3000` | HTTP port |
| `KEYS_DIR` | `keys` | Directory for key material used by credential/snippet workflows |
| `DB_PATH` | `data/sessions.db` | SQLite database file |
| `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](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`. |
@@ -62,13 +68,12 @@ The server listens on port **3000** by default.
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):
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:
- `/environments`
- `/credentials`
- `/snippets`
- `/sessions`
- `/scenarios`
```bash
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**:
@@ -100,7 +105,7 @@ Watch mode:
npm -w server run test:watch
```
Enable verbose NestJS log output during tests:
Print the NestJS logs of the test app (they're silenced by default; `DEBUG=test`):
```bash
npm -w server run test:debug
@@ -198,7 +203,7 @@ Everything is served by the single `liqa` container at **http://localhost:13000*
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.
The SQLite database and stored files are persisted in `./data/`, which is volume-mounted into the container.
Stop and remove containers:
@@ -216,7 +221,7 @@ 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.
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
@@ -224,9 +229,13 @@ The client (`client/`) is a React 19 + TypeScript SPA built with Vite. It provid
|---|---|
| React 19 + TypeScript | UI framework |
| Vite 6 | Dev server and bundler |
| react-router-dom (HashRouter) | Client-side routing |
| 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 |
@@ -236,29 +245,30 @@ The client (`client/`) is a React 19 + TypeScript SPA built with Vite. It provid
```
client/
src/
api/ API client modules (environments, credentials, snippets, sessions, scenarios)
hooks/ useTheme (light/dark persistence)
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
pages/ Environment/Credential/Snippet/Session/Scenario/Run pages
ui/ Reusable component library
Badge, Breadcrumbs, Button, Card, Input, Select,
SidePanel, Table, ThemeSwitcher, Timestamp
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 all ui/ components
stories/ *.stories.tsx for ui/ components
```
### Routing
Hash-based routing (`/#/path`) avoids conflicts with the Vite dev-server proxy. Default route redirects to `/#/scenarios`.
`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](architecture.md)), so they work on refresh.
| Route | Page |
|---|---|
| `/#/environments` | Environment list |
| `/#/credentials` | Credential list |
| `/#/snippets` | Snippet list |
| `/#/sessions` | Session list |
| `/#/scenarios` | Scenario list |
| `/#/runs` | Cross-scenario runs list |
| `/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