# 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**:
1. `AI_PROVIDER` env var if set
2. `ANTHROPIC_API_KEY` set (and no `OPENAI_API_KEY`) → `anthropic`
3. `OPENAI_API_KEY` set → `openai`
4. 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

```bash
# Install dependencies
pnpm install

# Apply database migrations
pnpm db:migrate

# (Optional) Seed development data
pnpm db:seed
```

---

## Running Locally

```bash
# 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

```bash
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.

```bash
# 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:
```bash
export PLAYWRIGHT_DOCKER_IMAGE=mcr.microsoft.com/playwright:v1.44.0-jammy
```

---

## GitHub Webhook Configuration

1. Generate a webhook secret (the platform does this automatically via `webhooks.configure`)
2. In GitHub: **Settings → Webhooks → Add webhook**
   - Content type: `application/json`
   - Events: `push` and/or `pull_request`
3. Copy the platform-provided URL and secret into GitHub
4. 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:
```bash
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`](../docker/README.md) for details.

```bash
# 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
```