Getting Started

This guide walks you through setting up the bopen monorepo for local development.

Prerequisites

Tool	Version	Purpose
Node.js	≥ 20	Frontend (apps/web) and docs (docs/)
Rust	≥ 1.75	Payment service
Docker	Latest	Local Keycloak, container builds
AWS CLI	Latest	Infrastructure deployment
PostgreSQL client (psql)	Latest	Run database scripts manually

Clone and install

git clone <repository-url>
cd bopen

# Frontend dependencies
cd apps/web && npm install && cd ../..

# Documentation dependencies
cd docs && npm install && cd ..

Running locally

1. Database

docker compose up -d   # starts PostgreSQL on localhost:5432

Apply migrations:

export DATABASE_URL="postgres://bopen_app:bopen@localhost:5432/bopen"

for f in \
  database/scripts/roles/001_app_roles.sql \
  database/scripts/init/001_extensions.sql \
  database/scripts/migrations/001_initial_schema.sql \
  database/scripts/migrations/002_permissions.sql \
  database/scripts/migrations/003_b2b_payments.sql \
  database/scripts/migrations/004_audit_enforcement.sql \
  database/scripts/migrations/005_merchant_enrichment.sql \
  database/scripts/migrations/006_payment_consents.sql \
  database/scripts/migrations/007_audit_ledger_enrichment.sql \
  database/scripts/migrations/009_rename_client_id.sql \
  database/scripts/seeds/001_dev_seed.sql \
  database/scripts/seeds/002_dev_b2b_seed.sql \
  database/scripts/seeds/003_dev_merchant_enrichment_seed.sql
do
  psql "$DATABASE_URL" -f "$f"
done

2. Keycloak (local dev)

docker run --rm -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.2.5 start-dev

Admin console: http://localhost:8080/admin.

See Keycloak Setup for creating test realms.

3. Payment service

DATABASE_URL="postgres://bopen_app:bopen@localhost:5432/bopen" \
MOCK_BANK_BASE_URL="http://localhost:3000" \
KEYCLOAK_URL="http://localhost:8080" \
KEYCLOAK_ADMIN_USER="admin" \
KEYCLOAK_ADMIN_PASSWORD="admin" \
DB_SSL_MODE="disable" \
cargo run -p payment-service

Health check: http://localhost:8081/health.

4. Frontend

cd apps/web
NEXT_PUBLIC_PAYMENT_API_URL=http://localhost:8081 \
NEXT_PUBLIC_KEYCLOAK_URL=http://localhost:8080 \
npm run dev

Open http://localhost:3000.

From the home page:

• Acquirer Portal → /portal/login (create a realm first via /portal/register)
• Pay by bank checkout → /checkout?amount=150.00&currency=GBP&merchant=Demo+Store
• Embeddable widget demo → /widget-demo.html
• Dev harness → /dev/merchant-harness

5. Documentation

cd docs && npm start

Open http://localhost:3001.

Using the dev harness

/dev/merchant-harness exercises the full payment flow:

1. Set amount, idempotency key, and merchant client ID
2. Select a simulated bank
3. Click Initiate A2A payment → calls POST /api/v1/payments
4. Mock bank redirect stub simulates SCA (approve or cancel)
5. Return page shows receipt with fee breakdown and audit trail

Toggle Use full SCA simulation to use /dev/mock-bank-sca (login + OTP).

Embeddable widget

Open http://localhost:3000/widget-demo.html to preview the embeddable checkout widget. Change amount, currency, and API URL, then click Launch widget — the event log on the left captures all BOPEN_* lifecycle events.

Building for production

# Frontend — static export
cd apps/web && npm run build

# Payment service
cargo build --release

# Documentation
cd docs && npm run build

Deployed dev environment

URL	Purpose
dev-checkout.bopenbanking.com	Consumer checkout. Not the widget demo — that build predates the widget's creation and 404s live; run it locally instead (see Checkout Widget — Demo)
dev-acquirer.bopenbanking.com	Acquirer portal
dev-auth.bopenbanking.com	Keycloak IAM — HTTP only, no ACM certificate (see IAM)
dev.api.bopenbanking.com	Payment API
doc.bopenbanking.com	This documentation