Skip to main content

​
Overview

The Docker setup provides a complete boop network environment for development and testing. All services run in containers, making it easy to get started quickly.
Prerequisites: Docker Desktop or Docker Engine with Docker Compose installed.

​
Quick Start

1

Clone Repository

git clone https://github.com/boop-network/boop-network.git
cd boop-network
2

Start Services

cd docker/standalone
docker-compose up -d
3

Verify Setup

# Check all services are running
docker-compose ps

# Test API Gateway health
curl http://localhost:40401/health

​
Service Configuration

​
Available Docker Compositions

Path: docker/minimal/What it includes:
  • Core services only
  • External database required
  • No mock services
Use when: Lighter resource usage, custom database setup
cd docker/minimal
docker-compose up -d
Path: docker/development/What it includes:
  • All services with development optimizations
  • Hot reload enabled
  • Debug logging
  • Development tools
Use when: Active development with code changes
cd docker/development
docker-compose up -d

​
Service Ports

When running with Docker, these ports are exposed:
ServiceContainer PortHost PortDescription
API Gateway4040140401Main REST API
Bridge Service4040340403WebSocket bridge
Mock PVS80818081Palm scanner interface
Mock Vendor80808080Test vendor system
Mock User30003000User registration
PostgreSQL54325432Database
Redis63796379Cache

​
Environment Variables

Customize the Docker setup with environment variables: 
# Copy example and modify
cp docker/standalone/.env.example docker/standalone/.env

# Edit configuration
POSTGRES_PASSWORD=your_secure_password
REDIS_PASSWORD=your_redis_password
LOG_LEVEL=debug
RUST_BACKTRACE=1

​
Key Environment Variables

# Logging
LOG_LEVEL=debug                    # trace, debug, info, warn, error
RUST_LOG=boop_network=debug       # Rust-specific logging
RUST_BACKTRACE=1                   # Enable backtraces

# Database
DATABASE_URL=postgresql://user:pass@postgres/boop
POSTGRES_PASSWORD=secure_password

# Redis
REDIS_URL=redis://redis:6379
REDIS_PASSWORD=redis_password

# API Configuration
API_PORT=40401
BRIDGE_PORT=40403

# Worker threads
TOKIO_WORKER_THREADS=4

# Database connections
DATABASE_MAX_CONNECTIONS=50
DATABASE_MIN_CONNECTIONS=5

# Request timeouts
REQUEST_TIMEOUT=30s
DATABASE_TIMEOUT=10s

# Memory settings
RUST_MIN_STACK=8388608

# Development mode (more verbose logging, relaxed security)
DEVELOPMENT_MODE=true

# CORS settings for development
CORS_ALLOW_ORIGIN=http://localhost:3000
CORS_ALLOW_CREDENTIALS=true

# JWT settings
JWT_SECRET=dev_secret_change_in_production
JWT_EXPIRES_IN=24h

​
Development Workflows

​
Code Changes & Hot Reload

1

Enable Development Mode

cd docker/development
docker-compose up -d
2

Mount Source Code

# In docker-compose.yml
services:
  api-gateway:
    volumes:
      - "../../:/workspace"
    command: cargo watch -x "run --bin api-gateway"
3

View Logs

# Follow logs for specific service
docker-compose logs -f api-gateway

# Follow all service logs
docker-compose logs -f

​
Database Management

# Run database migrations
docker-compose exec api-gateway sqlx migrate run

# Create new migration
docker-compose exec api-gateway sqlx migrate add create_new_table

# Reset database (development only)
docker-compose down -v
docker-compose up -d postgres
docker-compose exec api-gateway sqlx database create
docker-compose exec api-gateway sqlx migrate run

# Connect to PostgreSQL
docker-compose exec postgres psql -U boop -d boop

# Dump database
docker-compose exec postgres pg_dump -U boop boop > backup.sql

# Restore database
docker-compose exec -T postgres psql -U boop -d boop < backup.sql

# Add pgAdmin for database management
# Add to docker-compose.yml:
services:
  pgadmin:
    image: dpage/pgadmin4:latest
    environment:
      - [email protected]
      - PGADMIN_DEFAULT_PASSWORD=admin
    ports:
      - "5050:80"
    depends_on:
      - postgres

​
Testing with Mock Services

URL: http://localhost:8081Features:
  • Simulate palm scans
  • Register new users
  • Test different scan qualities
  • Trigger various error conditions
Usage:
# Register a new user
curl -X POST http://localhost:8081/register \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test_user_1"}'

# Simulate palm scan
curl -X POST http://localhost:8081/scan \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test_user_1", "quality": 95}'
URL: http://localhost:8080Features:
  • Simulate vendor authentication requests
  • Test payment flows
  • Validate attribute requirements
  • Monitor authentication results
Usage:
# Create authentication context
curl -X POST http://localhost:8080/auth \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "amount": 1000,
    "attributes": ["email", "pseudonym"]
  }'
URL: http://localhost:3000Features:
  • User registration interface
  • Attribute management
  • Consent settings
  • User profile management
Usage: Open in browser and follow the UI workflow

​
Monitoring & Debugging

​
Service Health Monitoring

# Check all services
./scripts/health-check.sh

# Check specific service
curl http://localhost:40401/health

# Service-specific health endpoints
curl http://localhost:8081/health    # Mock PVS
curl http://localhost:8080/health    # Mock Vendor
curl http://localhost:3000/health    # Mock User

​
Performance Monitoring

# Add Prometheus for metrics
# In docker-compose.yml:
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

# Add Jaeger for tracing
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
      - "14268:14268"
    environment:
      - COLLECTOR_OTLP_ENABLED=true

​
Troubleshooting

​
Common Issues

Symptoms: Containers exit immediately or fail health checksSolutions:
# Check container logs
docker-compose logs service-name

# Verify ports aren't in use
netstat -tulpn | grep :40401

# Reset Docker state
docker-compose down -v
docker system prune -a
docker-compose up -d
Symptoms: Services can’t connect to PostgreSQLSolutions:
# Check PostgreSQL is running
docker-compose ps postgres

# Test database connection
docker-compose exec postgres psql -U boop -d boop -c "SELECT 1;"

# Check environment variables
docker-compose exec api-gateway env | grep DATABASE

# Reset database
docker-compose down postgres
docker volume rm $(docker volume ls -q | grep postgres)
docker-compose up -d postgres
Symptoms: API requests are slow, timeouts occurSolutions:
# Check resource usage
docker stats

# Increase Docker resources (Docker Desktop Settings)
# Memory: 8GB+, CPU: 4+ cores

# Use faster Docker storage driver
# Enable "Use the new Virtualization framework"

# Monitor individual service performance
docker-compose exec api-gateway top

​
Development Tips

Pro Tip: Use docker-compose logs -f | grep ERROR to monitor for errors across all services in real-time.

Fast Iteration

Use volume mounts for code changes without rebuilding containers

Clean Slate

Run docker-compose down -v to reset all data for fresh testing

Resource Monitoring

Keep docker stats running to monitor container resource usage

Log Aggregation

Use docker-compose logs -f -t | tee development.log to capture all logs
Need help? Check the Troubleshooting Guide for solutions to common development issues.