Skip to main content

​
Prerequisites

Before starting, ensure you have:

Docker

Docker Desktop or Docker Engine

Rust

Rust toolchain 1.70+

Git

Git for cloning repos

​
Installation Commands

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install --cask docker
brew install rust git

# Start Docker Desktop
open -a Docker

​
Quick Start with Docker

The fastest way to run boop locally: 
# Clone the repository
git clone https://github.com/boop-network/boop-network.git
cd boop-network

# Start all services
cd docker/standalone
docker-compose up -d

# Verify services are running
docker-compose ps
Services will be available at:
ServiceURLPurpose
API Gatewayhttp://localhost:40401Main API endpoint
MPC Gatewayhttp://localhost:40402Biometric processing
Bridge Servicews://localhost:40403WebSocket connections
Ledgerhttp://localhost:40404Transaction log
Attribute Servicehttp://localhost:40405User attributes
Grafanahttp://localhost:3000Monitoring dashboard

​
Running Mock Services

​
Mock PVS (Palm Scanner)

The mock PVS simulates a palm scanner device: 
# Basic usage
cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  register

# With web interface (recommended for testing)
cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  serve 0.0.0.0:8081
Access the web interface at http://localhost:8081 for easy testing

​
Mock Vendor

Simulates a vendor backend: 
# Payment vendor
cargo run --bin mock-vendor -- \
  0.0.0.0:8080 \
  payment 2500  # $25.00

# Access control vendor
cargo run --bin mock-vendor -- \
  0.0.0.0:8080 \
  event

​
Mock User

Simulates user actions: 
# Register a user
cargo run --bin mock-user -- \
  http://localhost:40401 \
  register "intent_link_here"

# Set attributes
cargo run --bin mock-user -- \
  http://localhost:40401 \
  attribute email "[email protected]"

​
Complete Test Flow

Follow these steps to test a complete authentication flow:
1

Start Core Services

cd docker/standalone
docker-compose up -d
2

Start Mock Vendor

cargo run --bin mock-vendor -- \
  0.0.0.0:8080 \
  payment 1000
3

Start Mock PVS Web UI

cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  serve 0.0.0.0:8081
4

Configure PVS

# Get configuration intent
cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  configuration

# Configure with vendor endpoint
cargo run --bin mock-operator -- \
  --pvs-backend-endpoint localhost:8080 \
  --api-addr http://localhost:40401 \
  pvs-configuration "INTENT_LINK"
5

Register Test User

Open http://localhost:8081, click “Register”, then:
cargo run --bin mock-user -- \
  http://localhost:40401 \
  register "INTENT_LINK_FROM_UI"
6

Test Authentication

In the web UI, click “Payment” to simulate authentication

​
Using Seeds for Deterministic Testing

Seeds ensure consistent palm patterns between registration and authentication: 
# Register with seed
cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  --seed "alice" \
  register

cargo run --bin mock-user -- \
  http://localhost:40401 \
  --seed "alice" \
  register "INTENT_LINK"

# Authenticate with same seed
cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  --vendor-addr localhost:8080 \
  --seed "alice" \
  auth

​
Database Management

​
Reset Databases

# Stop services
docker-compose down

# Remove volumes (this deletes all data)
docker-compose down -v

# Restart fresh
docker-compose up -d

​
Access Databases

# SQLite (default for development)
docker exec -it mpc-gateway sqlite3 /data/mpc-gateway.db

# PostgreSQL (if configured)
docker exec -it postgres psql -U boop

​
Monitoring & Debugging

​
View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api-gateway

# With timestamps
docker-compose logs -f --timestamps

​
Grafana Dashboard

  1. Open http://localhost:3000
  2. Default credentials: admin/admin
  3. View pre-configured dashboards

​
Debug Mode

Set environment variables for verbose logging: 
export RUST_LOG=debug
export RUST_BACKTRACE=full

# Run service with debug output
cargo run --bin api-gateway-bin

​
Common Issues

# Find process using port
lsof -i :40401

# Kill process
kill -9 <PID>

# Or use different ports in docker-compose.yml

# Check Docker daemon
docker version

# Restart Docker
# macOS: Restart Docker Desktop
# Linux: sudo systemctl restart docker

# Use IP address format, not localhost
cargo run --bin mock-pvs -- \
  --api-addr http://localhost:40401 \
  serve 0.0.0.0:8081  # Correct

# NOT: serve localhost:8081 (incorrect)
Ensure you use the same seed for registration and authentication:
# Both commands must use same seed
--seed "test-user"

​
Testing Your Vendor Integration

Once boop is running locally, test your vendor integration: 
// Point to local boop instance
const boop = new BoopClient({
  vendorId: 'ven_test_local',
  apiKey: 'sk_test_local',
  apiUrl: 'http://localhost:40401'  // Local API
});

// Create authentication
const auth = await boop.createAuthentication({
  type: 'payment',
  amount: 2500
});

// Trigger auth using mock PVS web UI
// Open http://localhost:8081 and click "Payment"

​
Performance Testing

​
Load Testing

# Install k6
brew install k6

# Run load test
k6 run scripts/load-test.js

​
Benchmark

# Benchmark API endpoints
ab -n 1000 -c 10 http://localhost:40401/health

​
Next Steps

Testing Vendors

Test vendor integrations

Architecture

System architecture