Deployment & Setup

Setup instructions for running the full E2E testing platform.

Prerequisites

Node.js 18+
pnpm 9+
Docker (required for test execution)
PostgreSQL 15+
Python 3.11+ (for the AI service)

Environment Variables

Main API (`apps/api`)

Variable	Required	Description
`DATABASE_URL`	Yes	PostgreSQL connection string: `postgresql://user:pass@host:5432/db`
`API_URL`	Yes	Base URL of the API: `https://api.yourdomain.com`
`APP_URL`	Yes	Base URL of the web app: `https://yourdomain.com`
`BETTER_AUTH_SECRET`	Yes	Random secret for session signing (min 32 chars)
`GITHUB_CLIENT_ID`	Yes	GitHub OAuth app client ID
`GITHUB_CLIENT_SECRET`	Yes	GitHub OAuth app client secret
`JWT_SECRET`	Yes	Secret for signing JWTs (min 32 chars)
`REDIS_URL`	Yes	Redis connection string: `redis://localhost:6379`
`AI_SERVICE_URL`	No	AI service base URL (default: `http://localhost:8000`)

AI Service (`packages/ai-service`)

Variable	Required	Description
`OPENAI_API_KEY`	No*	OpenAI API key — enables real AI responses
`ANTHROPIC_API_KEY`	No*	Anthropic API key — alternative to OpenAI
`AI_PROVIDER`	No	Force a specific provider: `openai`, `anthropic`, `mock`
`OPENAI_MODEL`	No	OpenAI model override (default: `gpt-4o`)

*If neither key is set, the service uses mock provider (returns deterministic placeholder data).

Provider auto-detection:

AI_PROVIDER env var if set
ANTHROPIC_API_KEY set (and no OPENAI_API_KEY) → anthropic
OPENAI_API_KEY set → openai
Neither → mock

Docker Playwright Executor

Variable	Required	Description
`PLAYWRIGHT_DOCKER_IMAGE`	No	Override Docker image (default: `mcr.microsoft.com/playwright:v1.42.0-jammy`)

Installation

# Install dependencies
pnpm install

# Apply database migrations
pnpm db:migrate

# (Optional) Seed development data
pnpm db:seed

Running Locally

# Start all services in development mode
pnpm dev

# Or individually:
pnpm --filter @izri/api dev          # Node API on :4000
pnpm --filter @izri/web dev          # Web app on :3000
cd packages/ai-service && uvicorn main:app --reload --port 8000  # AI service

AI Service Setup

cd packages/ai-service

# Create virtualenv
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set your API key
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...

# Start
uvicorn main:app --host 0.0.0.0 --port 8000

Verify: curl http://localhost:8000/health

Docker Setup for Test Execution

The DockerPlaywrightExecutor requires Docker to be running on the host where the Node.js API runs.

# Verify Docker is available
docker --version
docker run --rm hello-world

# Pull the Playwright image in advance (optional, ~1.8 GB)
docker pull mcr.microsoft.com/playwright:v1.42.0-jammy

The executor mounts your test directory as a read-only volume (/tests) inside the container and runs npx playwright test from that directory.

Custom image: Set PLAYWRIGHT_DOCKER_IMAGE to use a different version:

export PLAYWRIGHT_DOCKER_IMAGE=mcr.microsoft.com/playwright:v1.44.0-jammy

GitHub Webhook Configuration

Generate a webhook secret (the platform does this automatically via webhooks.configure)
In GitHub: Settings → Webhooks → Add webhook
- Content type: application/json
- Events: push and/or pull_request
Copy the platform-provided URL and secret into GitHub
To enable commit status checks, configure a GitHub token in your project settings

The webhook endpoint rate-limits to 30 requests/minute per IP.

Database Schema Notes

The test_runs table includes:

commit_sha — the Git commit that triggered the run (indexed for dedup)
executor_type — enum: docker | local (default: docker)
results — JSONB column with the full structured test report

Run migrations after pulling changes:

pnpm db:migrate

Docker Compose (Full Stack)

A docker/ directory contains Docker Compose configuration for running the full stack in containers. See docker/README.md for details.

# Start full stack
docker compose -f docker/docker-compose.yml up

# Or with overrides for development
docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up