# Samplebeacon Docker — local dashboard & metrics collector

Run the full Samplebeacon dashboard stack locally with Docker Compose. This mirrors the CI perimeter workflow webhook target (`POST /api/samplebeacon/scan`).

## Prerequisites

- Docker Desktop or Docker Engine 24+
- Docker Compose v2

## Quick start

```bash
cd ai-platform
cp docker/env.samplebeacon.example .env   # optional
npm run samplebeacon:docker
```

Open:

- Samplebeacon UI: http://localhost:54355/samplebeacon-dashboard/
- Dashboard API: http://localhost:54355/api/samplebeacon/dashboard
- AI validation alias: http://localhost:54355/api/ai-validation/dashboard

## Profiles

| Command | Services |
|---------|----------|
| `npm run samplebeacon:docker` | Dashboard only |
| `npm run samplebeacon:docker:dev` | Dashboard + live mounts (`.samplebeacon`, `web/data`) |
| `npm run samplebeacon:docker:full` | Dashboard + metrics collector + Postgres + Redis |
| `npm run samplebeacon:docker:down` | Stop full stack |

### Metrics collector

The collector profile triggers `POST /api/samplebeacon/scan` on an interval (default 600s), keeping `.samplebeacon/report.json` and `history.json` fresh for the UI.

```bash
docker compose -f docker-compose.samplebeacon.yml --profile collector up -d
```

Environment:

| Variable | Default | Purpose |
|----------|---------|---------|
| `SAMPLEBEACON_COLLECT_INTERVAL_SEC` | `600` | Seconds between scans |
| `SAMPLEBEACON_DASHBOARD_TOKEN` | — | Optional Bearer token |

## GitHub Actions webhook

Set repository secrets for the [perimeter workflow](../../.github/workflows/samplebeacon-perimeter.yml):

| Secret | Example |
|--------|---------|
| `SAMPLEBEACON_DASHBOARD_URL` | `http://host.docker.internal:54355` (local tunnel) or your deployed URL |
| `SAMPLEBEACON_DASHBOARD_TOKEN` | Optional auth token |

The workflow POSTs to `/api/samplebeacon/scan` after each CI run.

## Phase 2 database

The `full` profile starts Postgres and Redis (same credentials as `docker-compose.phase2.yml`) and sets:

```
ENABLE_DATABASE=true
ENABLE_REDIS=true
```

Validate compose files in CI:

```bash
npm run samplebeacon:docker:config
```

## Files

| Path | Purpose |
|------|---------|
| `docker-compose.samplebeacon.yml` | Base stack |
| `docker-compose.samplebeacon.dev.yml` | Dev bind mounts |
| `docker-compose.samplebeacon.full.yml` | DB/Redis wiring |
| `docker/Dockerfile.dashboard` | Node 20 dashboard image |
| `docker/samplebeacon-collector.sh` | Periodic scan trigger |

## Troubleshooting

**Port 54355 in use** — set `SAMPLEBEACON_PORT=54356` in `.env`.

**Empty dashboard** — run a scan once:

```bash
curl -X POST http://localhost:54355/api/samplebeacon/scan -H "Content-Type: application/json" -d "{}"
```

**Build slow** — `.dockerignore` excludes `node_modules`, tests, and archive docs.

See also: [CI.md](./CI.md), [GITHUB-ACTION-QUICKSTART.md](./GITHUB-ACTION-QUICKSTART.md)
