OBP-API/development/docker at develop · OpenBankProject/OBP-API · GitHub
Skip to content

docker

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docker

README.md

OBP-API Docker Development Setup

This Docker Compose setup provides a complete live development environment for OBP-API with Redis caching support and hot reloading capabilities.

Services

🏦 obp-api-app

  • Main OBP-API application with live development mode
  • Built with Maven + Eclipse Temurin 25 (see Dockerfile / Dockerfile.dev)
  • Runs the packaged jar via entrypoint.sh (java -jar obp-api.jar)
  • Port: 8080
  • Features: Hot reloading, incremental compilation, live props changes

🔴 obp-api-redis

  • Redis cache server
  • Version: Redis 7 Alpine
  • Internal port: 6379
  • External port: 6380 (configurable)
  • Persistent storage with AOF

Quick Start

  1. Prerequisites

    • Docker and Docker Compose installed
    • Local PostgreSQL database running
    • Props file configured at obp-api/src/main/resources/props/default.props

  2. Start services

    cd development/docker
docker-compose up --build

  3. Access application

Configuration

Database Connection

You can configure the database connection in multiple ways:

Option 1: Props file (traditional):

db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://host.docker.internal:5432/obp_mapped?user=obp&password=yourpassword

Option 2: Environment variables (recommended for Docker): The setup automatically overrides database settings via environment variables, so you can configure without modifying props files.

Redis Configuration

Redis is configured automatically using OBP-API's environment variable override system:

# Automatically set by docker-compose.yml:
OBP_CACHE_REDIS_URL=redis      # Connect to redis service
OBP_CACHE_REDIS_PORT=6379      # Internal Docker port
OBP_DB_URL=jdbc:postgresql://host.docker.internal:5432/obp_mapped?user=obp&password=f

Custom Redis Port

To customize configuration, edit .env:

# .env file
OBP_CACHE_REDIS_PORT=6381
OBP_DB_URL=jdbc:postgresql://host.docker.internal:5432/mydb?user=myuser&password=mypass

Or set environment variables:

export OBP_CACHE_REDIS_PORT=6381
export OBP_DB_URL="jdbc:postgresql://host.docker.internal:5432/mydb?user=myuser&password=mypass"
docker-compose up --build

Container Names

All containers use consistent obp-api-* naming:

  • obp-api-app - Main application
  • obp-api-redis - Redis cache server
  • obp-api-network - Docker network
  • obp-api-redis-data - Redis data volume

Development Features

Props File Override

The setup mounts your local props directory:

volumes:
  - ../../obp-api/src/main/resources/props:/app/props

Environment variables take precedence over props files using OBP's built-in system:

  • cache.redis.url → OBP_CACHE_REDIS_URL
  • cache.redis.port → OBP_CACHE_REDIS_PORT
  • db.url → OBP_DB_URL

Live Development Features

Live configuration: Dockerfile.dev builds in the container and starts the jar through entrypoint.sh. Props and resources are volume-mounted from the host:

  • ✅ Props file changes - picked up from the mount (restart the container to apply)
  • ✅ Incremental builds - Maven reuses the container's local repository between builds
  • ⚠️ Scala code changes - require a rebuild/restart; there is no in-place reload

Volume Mounts for Development:

# Automatically mounted by docker-compose:
volumes:
  - ../../obp-api/src/main/resources/props:/app/props  # Live props updates
  # Source code is copied during build for optimal performance

Useful Commands

Service Management

# Start services
docker-compose up -d

# View logs
docker-compose logs obp-api-app
docker-compose logs obp-api-redis

# Stop services  
docker-compose down

# Rebuild and restart
docker-compose up --build

Redis Operations

# Connect to Redis CLI
docker exec -it obp-api-redis redis-cli

# Check Redis keys
docker exec obp-api-redis redis-cli KEYS "*"

# Monitor Redis commands
docker exec obp-api-redis redis-cli MONITOR

Container Inspection

# List containers
docker-compose ps

# Execute commands in containers
docker exec -it obp-api-app bash
docker exec -it obp-api-redis sh

Troubleshooting

Redis Connection Issues

  • Check if OBP_CACHE_REDIS_URL=redis is set correctly
  • Verify Redis container is running: docker-compose ps
  • Test Redis connection: docker exec obp-api-redis redis-cli ping

Database Connection Issues

  • Ensure local PostgreSQL is running
  • Verify host.docker.internal resolves: docker exec obp-api-app ping host.docker.internal
  • Check props file is mounted: docker exec obp-api-app ls /app/props/

Props Loading Issues

  • Check external props are detected: docker-compose logs obp-api-app | grep "external props"
  • Verify environment variables: docker exec obp-api-app env | grep OBP_

Environment Variables

The setup uses OBP-API's built-in environment override system:

Props File Property Environment Variable Default Description
cache.redis.url OBP_CACHE_REDIS_URL redis Redis hostname
cache.redis.port OBP_CACHE_REDIS_PORT 6379 Redis port
cache.redis.password OBP_CACHE_REDIS_PASSWORD - Redis password
db.url OBP_DB_URL jdbc:postgresql://host.docker.internal:5432/obp_mapped?user=obp&password=f Database connection URL

Network Architecture

Host Machine
├── PostgreSQL :5432
├── Props Files (mounted) → Docker Container
└── Docker Network (obp-api-network)
    ├── obp-api-app :8080 → :8080 (Live Development Mode)
    └── obp-api-redis :6379 → :6380 (Persistent Cache)

Connection Flow:

  • OBP-API ↔ Redis: Internal Docker network (redis:6379)
  • OBP-API ↔ PostgreSQL: Host connection (host.docker.internal:5432)
  • Props Files: Live mounted from host (/app/props/)
  • Redis External: Accessible via localhost:6380

Development Benefits

⚡ Live Development Mode (Dockerfile.dev)

  • Single-stage build optimized for development speed
  • Incremental compilation - only changed files are rebuilt
  • Live props updates - configuration changes without container restart
  • Security compliant - selective file copying (SonarQube approved)

🔧 Development vs Production

  • Current setup: Uses Dockerfile.dev for optimal development experience
  • Production ready: Can switch to Dockerfile for multi-stage production builds
  • Best of both: Live development with production-grade security practices

📋 Additional Notes

  • Redis data persists in obp-api-redis-data volume
  • Props files are live-mounted from host for instant updates
  • Environment variables override props file values automatically
  • Java 25, with the --add-opens flags the runtime needs (see entrypoint.sh)
  • All containers restart automatically unless stopped manually

🚀 Ready for live development!

cd development/docker
docker-compose up --build
# Start coding - changes are reflected automatically! 🔥

Pro Tips:

  • Make code changes and see them instantly without rebuilding
  • Update props files and they're loaded immediately
  • Use docker-compose logs obp-api -f to watch live application logs
  • Redis caching speeds up API responses significantly