# Containerized Demo Guide

This guide packages the Fan Passport demo as a two-service Docker Compose stack:

- **API** on `http://localhost:4000`
- **Web app** on `http://localhost:4173`

The image is intended for demo review, stakeholder walkthroughs, and short-lived QA environments. It is not a hardened production image.

## Prerequisites

- Docker Desktop or Docker Engine with Compose v2
- Open ports `4000` and `4173`
- A clean checkout of the repository

## Start the demo

From the repository root:

```bash
docker compose -f docker-compose.demo.yml up --build
```

When both services are healthy, open:

```text
http://localhost:4173
```

The API health check is available at:

```text
http://localhost:4000/health
```

If a deployment environment mounts the API under `/api`, the Compose health check also accepts `/api/health`.

## Run release checks against the containerized demo

In a second terminal:

```bash
node scripts/qa/release-preflight.mjs
API_BASE_URL=http://localhost:4000 node scripts/qa/http-smoke.mjs
npm run e2e --if-present
```

The release preflight is static and does not require the containers to be running. The HTTP smoke test and end-to-end tests should be run while the Compose stack is active.

## Environment values baked into the demo image

The Vite frontend reads `VITE_API_BASE_URL` at build time. The demo Docker build sets:

```text
VITE_API_BASE_URL=http://localhost:4000
```

The API service uses:

```text
PORT=4000
CORS_ORIGIN=http://localhost:4173
DEMO_MODE=true
```

To test a different API origin, rebuild with a different build arg:

```bash
docker compose -f docker-compose.demo.yml build --build-arg VITE_API_BASE_URL=http://localhost:4000
docker compose -f docker-compose.demo.yml up
```

## Stop and clean up

Stop the stack:

```bash
docker compose -f docker-compose.demo.yml down
```

Remove built images if you want a fully clean rebuild later:

```bash
docker compose -f docker-compose.demo.yml down --rmi local
```

## Common fixes

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Web loads but API actions fail | API origin mismatch in the Vite build | Rebuild with `VITE_API_BASE_URL=http://localhost:4000` and restart Compose. |
| API container is unhealthy | Port collision or health route unavailable | Confirm port `4000` is free and open `http://localhost:4000/health`. |
| Web container exits immediately | Web workspace preview script missing or build failed | Run `npm --workspace apps/web run build` locally and inspect the error. |
| Browser blocks requests | CORS origin mismatch | Confirm `CORS_ORIGIN=http://localhost:4173` in the API service environment. |
| Changes do not appear | Docker layer cache reused an older build | Run `docker compose -f docker-compose.demo.yml build --no-cache`. |

## Demo boundaries

This container setup uses the repository's demo data store and is suitable for public-progress walkthroughs. Before using it for real fan accounts, replace in-memory demo storage with persistent storage, add authentication, configure production-grade logging, and run a security review.