Documentation Index
Fetch the complete documentation index at: https://mintlify.com/davidG97/qa-flow/llms.txt
Use this file to discover all available pages before exploring further.
QA Flow ships as a pre-built Docker image (davidg1997/qa-flow) that bundles the React frontend, Express backend, Prisma database layer, and a Playwright-ready Chromium installation into a single container. You can reach that image in three ways: through the convenience npx launcher, by running Docker directly, or by cloning the repository and starting the development stack with pnpm. Choose the method that best fits your workflow.
npx (Recommended for Quick Use)
The npx launcher is the fastest path to a running QA Flow instance. It requires no global installation — npx downloads the CLI package on demand, which in turn pulls the Docker image and starts the container for you.Prerequisites
Start QA Flow
On first run the CLI pulls davidg1997/qa-flow:latest from Docker Hub. Subsequent runs use the cached image unless a newer version is available.Customize the Port
The default port is 3001. Use -p or --port to change it:npx @davidg97/qa-flow --port 8080
npx @davidg97/qa-flow -p 8080
Other CLI Flags
# Print the package version and exit
npx @davidg97/qa-flow --version
# Show full help text
npx @davidg97/qa-flow --help
Persistent Data
The launcher automatically creates and mounts three named Docker volumes so your data survives container restarts:| Volume | Mount Path in Container | Contents |
|---|
qa-flow-data | /app/data | SQLite database |
qa-flow-screenshots | /app/server/screenshots | Test screenshots |
qa-flow-recordings | /app/server/recordings | Session recordings |
JWT Secret
If the JWT_SECRET environment variable is not set, the CLI generates a cryptographically random 32-byte secret automatically for that session. For persistent deployments, set it explicitly so token validity is maintained across restarts:JWT_SECRET="your-secret-min-32-chars" npx @davidg97/qa-flow
A session-generated JWT_SECRET means all existing login sessions are invalidated whenever the container restarts. Always set a fixed JWT_SECRET for any non-throwaway deployment.
Docker
Running the Docker image directly gives you full control over environment variables, volume bindings, and container lifecycle without needing Node.js on the host.Basic Usage (SQLite — Local Storage)
docker run -it --rm \
-p 3001:3001 \
-v qa-flow-data:/app/data \
davidg1997/qa-flow
With Environment Variables
Set a fixed JWT_SECRET and explicit port for a stable deployment:docker run -it --rm \
-p 3001:3001 \
-e JWT_SECRET="your-secret-min-32-chars" \
-e PORT=3001 \
-v qa-flow-data:/app/data \
davidg1997/qa-flow
With Turso Cloud Database
Replace the default SQLite file with a Turso libSQL cloud database for a serverless, zero-ops data layer:docker run -it --rm \
-p 3001:3001 \
-e DATABASE_URL="libsql://your-db.turso.io" \
-e TURSO_AUTH_TOKEN="your-token" \
davidg1997/qa-flow
With Docker Compose
For a more manageable setup, use the official docker-compose.yml from the repository. It declares the same volumes and environment variables in a readable format and supports restart: unless-stopped for server deployments:services:
qa-flow:
image: davidg1997/qa-flow:latest
container_name: qa-flow
ports:
- "${PORT:-3001}:3001"
environment:
- NODE_ENV=${NODE_ENV:-production}
- PORT=3001
- DATABASE_URL=${DATABASE_URL:-file:/app/data/qa-flow.db}
- JWT_SECRET=${JWT_SECRET:-change-me-in-production}
volumes:
- qa-flow-data:/app/data
- qa-flow-screenshots:/app/server/screenshots
- qa-flow-recordings:/app/server/recordings
restart: unless-stopped
volumes:
qa-flow-data:
qa-flow-screenshots:
qa-flow-recordings:
The Docker image runs as a non-root user (qaflow) for improved security. The /app/data directory is pre-configured for SQLite writes by that user.
Local Development
Clone the repository and run the full development stack locally when you want to contribute to QA Flow, extend its node types, or experiment with the codebase.Prerequisites
Steps
Clone the repository
git clone https://github.com/davidG97/qa-flow.git
cd qa-flow
Install dependencies
Install all workspace packages with pnpm, then approve the post-install build scripts (press a to select all when prompted):pnpm install && pnpm approve-builds
When pnpm approve-builds prompts you to select which packages may run build scripts, press a to approve all of them. This is required for packages like Playwright that compile native bindings during install.
Set up the database
Copy the example environment file for the server, then run the Prisma migration and client generation:cp server/.env.example server/.env
pnpm db:migrate
pnpm db:generate
server/.env configures a local SQLite database at ./dev.db (relative to the server/ directory). Edit the file to point at a Turso cloud database if preferred. Start the development servers
Launch both the frontend (Vite) and backend (Express) with a single command:| Service | URL |
|---|
| Frontend (React + Vite HMR) | http://localhost:3000 |
| Backend (Express + API) | http://localhost:3001 |
dev:all script uses concurrently to run pnpm dev (Vite frontend) and pnpm --filter qa-flow-server dev (Express backend with watch mode) side-by-side in one terminal window. Useful Development Scripts
# Start only the backend server
pnpm server
# Run the full build (frontend + backend)
pnpm build:all
# Open Prisma Studio (database GUI)
pnpm db:studio
# Run backend tests
pnpm test
Environment Variables
All three installation methods respect the same set of environment variables. The table below covers every variable QA Flow currently recognises.
| Variable | Description | Default |
|---|
PORT | TCP port the Express server listens on inside the container | 3001 |
JWT_SECRET | Secret used to sign and verify JWT authentication tokens. Must be at least 32 characters for production use. | Auto-generated (random) if unset |
DATABASE_URL | Prisma database connection string. Use file:/path/to/db.db for SQLite or libsql://… for Turso. | file:/app/data/qa-flow.db |
TURSO_AUTH_TOKEN | Authentication token for Turso cloud databases. Required when DATABASE_URL points to a libsql:// endpoint. | (none) |
CDP_URL | URL of a remote Chrome DevTools Protocol endpoint (e.g. http://localhost:9222). When set, Playwright connects to that Chrome instance instead of launching a new one. | (none — launches headless Chromium) |
When running locally with pnpm dev:all, environment variables for the backend are read from server/.env. When running via Docker or npx, pass them with -e VAR=value flags or through a .env file referenced by Docker Compose.
Default Login Credentials
Regardless of installation method, QA Flow seeds the database with a default administrator account on first run:
| Field | Value |
|---|
| Email | admin@qaflow.com |
| Password | admin123 |
Change the default admin password and set a strong JWT_SECRET before deploying QA Flow on any server accessible outside of localhost. The default credentials are public knowledge and must not be used in production.