Installation

The Blackjack API can be run using Docker Compose for the quickest setup, or installed locally for development purposes. This guide covers both approaches.

Prerequisites

Java 21

Required for building and running the application

Maven

Build tool included via Maven Wrapper (mvnw)

Docker & Docker Compose

For containerized deployment (recommended)

Additional requirements for local development:

MongoDB 7.x
MySQL 8.0
IDE (IntelliJ IDEA recommended)

Installation Methods

# Clone the repository
git clone https://github.com/ccasro/5.01-Advanced-Spring-Framework.git
cd 5.01-Advanced-Spring-Framework

# Start all services (API, MongoDB, MySQL)
docker compose up -d

# View logs
docker compose logs -f api

Docker Compose Setup

The recommended way to run the Blackjack API is using Docker Compose, which automatically sets up all required services.

Docker Compose Configuration

The docker-compose.yml file defines three services:

docker-compose.yml

services:
  mysql:
    image: mysql:8.0
    container_name: blackjack-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: blackjack
      MYSQL_USER: blackjack
      MYSQL_PASSWORD: blackjack
    ports:
      - "3307:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost", "-uroot", "-proot" ]
      interval: 5s
      timeout: 3s
      retries: 20

  mongo:
    image: mongo:7
    container_name: blackjack-mongo
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db
    healthcheck:
      test: [ "CMD", "mongosh", "--eval", "db.adminCommand('ping')" ]
      interval: 5s
      timeout: 3s
      retries: 20

  api:
    image: ccasr/blackjack-api:latest
    container_name: blackjack-api
    ports:
      - "8080:8080"
    environment:
      SPRING_PROFILES_ACTIVE: docker
    depends_on:
      mysql:
        condition: service_healthy
      mongo:
        condition: service_healthy

volumes:
  mysql_data:
  mongo_data:

Start the Services

# Start all services in detached mode
docker compose up -d

# Check service status
docker compose ps

# View logs from all services
docker compose logs -f

# View logs from a specific service
docker compose logs -f api

Stop the Services

# Stop all services
docker compose down

# Stop and remove volumes (deletes all data)
docker compose down -v

The API service waits for MySQL and MongoDB to be healthy before starting, thanks to the depends_on healthcheck configuration.

Local Development Setup

For active development, you may prefer to run the application locally while using Docker only for databases.

Step 1: Start Database Services

Using Docker Compose
Manual Setup

Start only the database services:

docker compose up -d mysql mongo

MongoDB:

# Using Homebrew (macOS)
brew install mongodb-community@7
brew services start mongodb-community

# Or using Docker
docker run -d -p 27017:27017 --name blackjack-mongo mongo:7

MySQL:

# Using Homebrew (macOS)
brew install [email protected]
brew services start mysql
mysql -u root -e "CREATE DATABASE blackjack;"
mysql -u root -e "CREATE USER 'blackjack'@'localhost' IDENTIFIED BY 'blackjack';"
mysql -u root -e "GRANT ALL ON blackjack.* TO 'blackjack'@'localhost';"

# Or using Docker
docker run -d -p 3307:3306 \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=blackjack \
  -e MYSQL_USER=blackjack \
  -e MYSQL_PASSWORD=blackjack \
  --name blackjack-mysql mysql:8.0

Step 2: Configure Application Properties

The application uses Spring profiles for configuration. For local development, the local profile is activated by default. application-local.yml:

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/blackjack

  r2dbc:
    url: r2dbc:mysql://localhost:3307/blackjack
    username: blackjack
    password: blackjack

  flyway:
    enabled: true
    url: jdbc:mysql://localhost:3307/blackjack
    user: blackjack
    password: blackjack
    locations: classpath:db/migration

Note that MySQL is exposed on port 3307 when using Docker Compose to avoid conflicts with local MySQL installations on the default port 3306.

Step 3: Build and Run

# Build the project
./mvnw clean install

# Run the application
./mvnw spring-boot:run

# Or run with a specific profile
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

The application will start on http://localhost:8080.

Step 4: Verify Installation

# Check application health
curl http://localhost:8080/actuator/health

# Access Swagger UI
open http://localhost:8080/swagger-ui.html

Building from Source

If you want to build your own Docker image:

# Build the Docker image
docker build -t blackjack-api:local .

# Run your custom image
docker run -p 8080:8080 blackjack-api:local

The Dockerfile uses a multi-stage build:

Dockerfile

# ---- build stage ----
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app

COPY pom.xml .
RUN mvn -q -DskipTests dependency:go-offline

COPY src src
RUN mvn -q -DskipTests package

# ---- runtime stage ----
FROM eclipse-temurin:21-jre
WORKDIR /app

COPY --from=build /app/target/*.jar app.jar

EXPOSE 8080
ENTRYPOINT ["java","-jar","/app/app.jar"]

The multi-stage build keeps the final image size small by excluding Maven and build artifacts.

Database Configuration

The application uses two databases with different responsibilities:

MongoDB - Game State

Stores transient game data:

Game documents (deck, hands, status)
Player and dealer cards
Current game progress

Connection String:

mongodb://localhost:27017/blackjack  # Local
mongodb://mongo:27017/blackjack      # Docker

MySQL - Player Rankings

Stores persistent player data:

Player information
Win/loss statistics
Ranking scores

Connection Details:

Host: localhost (or mysql in Docker)
Port: 3307 (Docker) or 3306 (local)
Database: blackjack
Username: blackjack
Password: blackjack

Database migrations are managed automatically by Flyway on application startup. The schema is created from SQL scripts in src/main/resources/db/migration/.

Environment Profiles

The application supports multiple Spring profiles:

Profile	Purpose	Database Hosts
`local`	Local development	localhost:3307, localhost:27017
`docker`	Docker Compose	mysql:3306, mongo:27017
`prod`	Production deployment	Configured via environment variables

Activate a profile:

# Via Maven
./mvnw spring-boot:run -Dspring-boot.run.profiles=docker

# Via environment variable
export SPRING_PROFILES_ACTIVE=docker
./mvnw spring-boot:run

# Via Docker
docker run -e SPRING_PROFILES_ACTIVE=prod blackjack-api

Running Tests

The project includes comprehensive unit and integration tests:

# Run all tests
./mvnw test

# Run with coverage
./mvnw verify

# Run specific test class
./mvnw test -Dtest=GameControllerTest

Test coverage includes:

Domain layer (pure unit tests)
Application layer (use case tests with mocks)
Infrastructure layer (controller tests with WebTestClient)

Troubleshooting

Port already in use

If port 8080 is already in use:

# Check what's using port 8080
lsof -i :8080

# Kill the process or change the port
docker run -p 9090:8080 blackjack-api

Database connection failed

Ensure databases are running and healthy:

# Check Docker services
docker compose ps

# Test MongoDB connection
mongosh mongodb://localhost:27017/blackjack

# Test MySQL connection
mysql -h localhost -P 3307 -u blackjack -pblackjack blackjack

Flyway migration failed

If database migrations fail:

# Reset the database
docker compose down -v
docker compose up -d

# Or manually drop and recreate
mysql -h localhost -P 3307 -u root -proot -e "DROP DATABASE IF EXISTS blackjack; CREATE DATABASE blackjack;"

Maven build fails

Clear Maven cache and rebuild:

./mvnw clean
rm -rf ~/.m2/repository
./mvnw install

Get Started

Architecture

Game Operations

Player Management

Database

Deployment

Development

Prerequisites

Java 21

Maven

Docker & Docker Compose

Installation Methods

Docker Compose Setup

Docker Compose Configuration

Start the Services

Stop the Services

Local Development Setup

Step 1: Start Database Services

Step 2: Configure Application Properties

Step 3: Build and Run

Step 4: Verify Installation

Building from Source

Database Configuration

MongoDB - Game State

MySQL - Player Rankings

Environment Profiles

Running Tests

Troubleshooting

Next Steps

Quickstart Guide

API Reference

Development Guide

Deployment

Additional Resources

Build docs developers (and LLMs) love

Get Started

Architecture

Game Operations

Player Management

Database

Deployment

Development

​Prerequisites

Java 21

Maven

Docker & Docker Compose

​Installation Methods

​Docker Compose Setup

​Docker Compose Configuration

​Start the Services

​Stop the Services

​Local Development Setup

​Step 1: Start Database Services

​Step 2: Configure Application Properties

​Step 3: Build and Run

​Step 4: Verify Installation

​Building from Source

​Database Configuration

​MongoDB - Game State

​MySQL - Player Rankings

​Environment Profiles

​Running Tests

​Troubleshooting

​Next Steps

Quickstart Guide

API Reference

Development Guide

Deployment

​Additional Resources

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

Docker Compose Setup

Docker Compose Configuration

Start the Services

Stop the Services

Local Development Setup

Step 1: Start Database Services

Step 2: Configure Application Properties

Step 3: Build and Run

Step 4: Verify Installation

Building from Source

Database Configuration

MongoDB - Game State

MySQL - Player Rankings

Environment Profiles

Running Tests

Troubleshooting

Next Steps

Additional Resources