Getting started

Run Pepper locally for development or use Docker Compose for a full stack.

Prerequisites

Node.js 20+ and npm
Docker for PostgreSQL, Redis, and MinIO (or your own instances)
Worker process must run separately from the web app
Optional: Ollama for local AI scanning, or an OpenRouter/OpenAI API key
Optional: Subversion CLI on the worker for SVN scans

Local development setup

Clone and install

cd pepper-update-pepper-sast
npm install

Start infrastructure — PostgreSQL, Redis, MinIO (see project docker-compose.yml or README).

Configure environment

cp .env.example .env
# Edit DATABASE_URL, REDIS_URL, MINIO_*, NEXTAUTH_SECRET, NEXTAUTH_URL

See Environment variables for every option.

Initialize database
```
npx prisma db push
npm run db:seed
```
Default admin from seed: ADMIN_EMAIL / ADMIN_PASSWORD in .env.
Run the web app
```
npm run dev
```
Open http://localhost:3000 and sign in.
Run the worker (second terminal)
```
npm run worker
```
Without the worker, scans stay QUEUED forever.

First-time configuration checklist

Step	Where	Why
LLM provider + API key	Settings → LLM Config	AI SAST, secrets, suggest-fix, open fix PR
GitHub OAuth app	.env + Integrations	Import repos, private clone, fix PRs
Connect GitHub	Repositories	Link org account
Build gates (optional)	Settings → Build Gates	Fail scans that exceed thresholds
Invite team	Settings → Team	Multi-user access

Docker / on-prem quick start

See the root README.md for ./setup.sh, image versions, Ollama on the host, air-gapped deploy, backup/restore, and upgrade steps.

Scan scheduling is configured via the REST API (PUT /api/projects/{projectId}/schedule), not a dedicated UI on the project settings page. Project settings in the UI only edit name and description.

Verify the stack

GET /api/health — app health
Start a small New Scan from an upload or public GitHub repo
Watch scan status move from QUEUED → RUNNING → COMPLETED
Worker logs should show file enumeration and scanner progress