QAIra

QAIra is a QA management workspace with a Fastify backend, a React frontend, PostgreSQL for relational persistence, and MinIO-compatible object storage for binary test evidence.

This repo is now PostgreSQL-first. SQLite is no longer part of the runtime, which avoids the read-only database file issues that were happening with mounted .db files.

Stack

• Backend: Fastify on Node.js
• Frontend: React + Vite
• Database: PostgreSQL 16
• Attachments: MinIO / S3-compatible object storage through the official JavaScript SDK
• Containers: Docker Compose

Repo layout

• backend/api: Fastify API
• backend/db/schema.sql: PostgreSQL schema loaded on first database boot
• backend/db/seed.sql: sample data loaded on first database boot
• backend/docker-compose.yml: backend + PostgreSQL + MinIO
• docker-compose.full.yml: full stack with PostgreSQL, MinIO, API, and frontend
• docker-compose.platform.yml: full stack plus HAProxy, Prometheus, Grafana, Loki, Promtail, and OpenTelemetry Collector
• frontend: React app
• testengine: standalone Playwright worker plane
• openapi.yaml: API contract

Quick Start

Start everything from the repo root:

./qaira.sh up --stack full

Open the apps:

• Frontend: http://localhost:8080
• API: http://localhost:3000
• PostgreSQL: localhost:5432
• MinIO API: localhost:9000
• MinIO console: http://localhost:9001

On the first boot, the Postgres container creates the qaira database and automatically runs:

• backend/db/schema.sql
• backend/db/seed.sql

Operator Script

Use qaira.sh as the single root entrypoint for service relation config, image publishing, and compose deployment:

./qaira.sh config --stack full
./qaira.sh push
./qaira.sh deploy --stack platform
./qaira.sh deploy --stack testengine --yes

./qaira.sh config writes the resolved service contract to .qaira/<stack>.env. Override any endpoint or image with environment variables or --config <file>:

QAIRA_PUBLIC_URL=https://qaira.example.com \
QAIRA_API_BASE_URL=https://qaira.example.com/api \
./qaira.sh deploy --stack platform

The deploy command prints the target stack, compose file, frontend URL, API URLs, and Test Engine URL before it changes containers. Use --yes only from automation.

For AWS EC2 hosts, prefer the scripts in deploymentscripts:

deploymentscripts/aws-app-deploy.sh
QAIRA_API_BASE_URL=https://qaira.qualipal.in/api deploymentscripts/aws-testengine-deploy.sh
deploymentscripts/aws-status.sh
deploymentscripts/aws-logs.sh --stack app

Quick start: backend only

Run the backend and PostgreSQL without the frontend:

cd backend
docker pull postgres:16-alpine
docker compose up --build

You can also use:

cd backend
./start.sh

The API will be available at http://localhost:3000.

The Compose credentials are development defaults. Set unique MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, MINIO_ACCESS_KEY, and MINIO_SECRET_KEY values for every hosted environment; the API keeps these server-side and stores only object pointers and metadata in PostgreSQL.

Start Individual Services

From the repo root, target services through the same operator script:

./qaira.sh up --stack full postgres api
./qaira.sh up --stack full frontend
./qaira.sh up --stack testengine testengine

Platform stack

For the stronger Docker edge and observability layer:

docker compose -f docker-compose.platform.yml up -d

That stack adds:

• HAProxy on http://localhost
• Prometheus on http://localhost:9090
• Grafana on http://localhost:3001
• Loki on http://localhost:3100
• HAProxy stats on http://localhost:8404/stats

If port 80 is already used on the host, publish HAProxy on another host port:

QAIRA_HTTP_PORT=8081 docker compose -f docker-compose.platform.yml up -d

More detail is in PLATFORM_STACK.md.

Manual PostgreSQL setup

If you want to run Postgres yourself instead of using Compose, these are the explicit steps.

1. Pull the image:

docker pull postgres:16-alpine

2. Start PostgreSQL:

docker run --name qaira-postgres \
  -e POSTGRES_DB=qaira \
  -e POSTGRES_USER=qaira \
  -e POSTGRES_PASSWORD=qaira \
  -p 5432:5432 \
  -d postgres:16-alpine

3. Load the schema:

PGPASSWORD=qaira psql -h localhost -U qaira -d qaira -f backend/db/schema.sql

4. Load the sample data:

PGPASSWORD=qaira psql -h localhost -U qaira -d qaira -f backend/db/seed.sql

5. Run the API locally:

cd backend/api
npm install
DATABASE_URL=postgresql://qaira:qaira@localhost:5432/qaira npm start

6. Run the frontend locally in another terminal:

cd frontend
npm install
VITE_API_BASE_URL=http://localhost:3000 npm run dev

Sample login

The seed file creates these users:

• admin@testiny.ai / admin123
• member@testiny.ai / member123

Environment variables

Backend

• DATABASE_URL Example: postgresql://qaira:qaira@postgres:5432/qaira
• SESSION_SECRET
• CORS_ORIGIN
• LOG_LEVEL
• STORAGE_PROVIDER (minio for the bundled object store, or s3 for a compatible hosted endpoint)
• MINIO_ENDPOINT, MINIO_PORT, MINIO_USE_SSL
• MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, MINIO_REGION
• MAX_ATTACHMENT_BYTES (defaults to 100 MiB)

Attachment uploads are streamed through the authenticated API. PostgreSQL stores the QAira entity scope, object key, checksum, content type, and audit metadata; file bytes remain in object storage and downloads are lazy. Keep object-storage credentials on the API service only—never expose them through the frontend runtime config.

PostgreSQL container

• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD

Frontend

• QAIRA_API_BASE_URL for the container build/runtime config Example: http://localhost:3000 for docker-compose.full.yml, or /api when the frontend and API share the same public host behind HAProxy or a load balancer
• VITE_API_BASE_URL for local Vite development
• QAIRA_BACKEND_IMAGE to override the backend Docker Hub image
• QAIRA_FRONTEND_IMAGE to override the frontend Docker Hub image

Database behavior

• The official postgres:16-alpine image creates the database defined by POSTGRES_DB.
• The mounted SQL files in backend/db are executed only when the Postgres data directory is empty.
• Sample data is inserted from backend/db/seed.sql, so the backend and frontend have working starter content immediately.

Reset the database

If you want a fresh database and fresh seed data:

From the repo root:

docker compose -f docker-compose.full.yml down -v
docker compose -f docker-compose.full.yml pull
docker compose -f docker-compose.full.yml up -d

From the backend folder:

docker compose down -v
docker compose up --build

Notes

• docker-compose.full.yml now uses Docker Hub images by default:
• Backend: jayarajumetta/qaira-backend:latest
• Frontend: jayarajumetta/qaira-frontend:latest
• The frontend is configured to talk to http://localhost:3000 by default in local Docker workflows.
• The schema in backend/db/schema.sql is ordered for PostgreSQL foreign key creation, and seed.sql uses PostgreSQL boolean values.