From 0470f77b87d46a67d138b9e0037fe252f446c649 Mon Sep 17 00:00:00 2001 From: SvitlanaKovalova1 Date: Fri, 13 Mar 2026 13:57:04 +0200 Subject: [PATCH] chore: Improve Docker Compose setup for local development --- NEWS.md | 1 + docker/.env | 21 +- docker/README.md | 220 ++++++++++++++++++ docker/app-docker-compose.yml | 42 ++++ ...r-compose.yml => infra-docker-compose.yml} | 37 ++- src/main/resources/application-dev.properties | 53 +++++ 6 files changed, 346 insertions(+), 28 deletions(-) create mode 100644 docker/README.md create mode 100644 docker/app-docker-compose.yml rename docker/{docker-compose.yml => infra-docker-compose.yml} (55%) create mode 100644 src/main/resources/application-dev.properties diff --git a/NEWS.md b/NEWS.md index 87e73066..762fda07 100644 --- a/NEWS.md +++ b/NEWS.md @@ -17,6 +17,7 @@ * Adjust logging to hide sensitive data ([MODKBEKBJ-776](https://folio-org.atlassian.net/browse/MODKBEKBJ-776)) * Refactor code to comply with Checkstyle method length limit (max 25 lines) ([MODKBEKBJ-808](https://folio-org.atlassian.net/browse/MODKBEKBJ-808)) * Use GitHub workflow for CI/CD ([MODKBEKBJ-817](https://folio-org.atlassian.net/browse/MODKBEKBJ-817)) +* Improve Docker Compose setup for local development ([MODKBEKBJ-805](https://folio-org.atlassian.net/browse/MODKBEKBJ-805)) ### Dependencies * Bump `LIB_NAME` from `OLD_VERSION` to `NEW_VERSION` diff --git a/docker/.env b/docker/.env index a5de8acc..67cb66aa 100644 --- a/docker/.env +++ b/docker/.env @@ -1,12 +1,25 @@ COMPOSE_PROJECT_NAME=folio-mod-kb-ebsco-java + +# Environment name +ENV=folio + +# Module configuration +MODULE_PORT=8081 +MODULE_REPLICAS=1 +DEBUG_PORT=5005 + +# PostgreSQL configuration DB_HOST=postgres DB_PORT=5432 -DB_DATABASE=okapi_modules +DB_DATABASE=modules DB_USERNAME=folio_admin DB_PASSWORD=folio_admin + +# PgAdmin configuration +PGADMIN_PORT=5050 PGADMIN_DEFAULT_EMAIL=user@domain.com PGADMIN_DEFAULT_PASSWORD=admin -PGADMIN_PORT=5050 -ENV=folio -DEBUG_PORT=5005 +# WireMock (Okapi mock) configuration +WIREMOCK_PORT=9130 +OKAPI_URL=http://wiremock:8080 diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 00000000..6edfbed3 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,220 @@ +# 🐳 Docker Compose Setup for mod-kb-ebsco-java + +Local development environment for mod-kb-ebsco-java using Docker Compose. + +## 📋 Prerequisites + +- Docker and Docker Compose V2+ +- Java 21+ (for local development mode) +- Maven 3.6+ (for building the module) + +## 🏗️ Architecture + +Two compose files provide flexible development workflows: + +- **`infra-docker-compose.yml`**: Infrastructure services only (PostgreSQL, WireMock, etc.) +- **`app-docker-compose.yml`**: Full stack including the module (uses `include` to incorporate infra services) + +## ⚙️ Configuration + +Configuration is managed via the `.env` file in this directory. + +### Environment Variables + +| Variable | Default Value | Description | +|----------------------------|---------------------------|-----------------------------------| +| `COMPOSE_PROJECT_NAME` | `folio-mod-kb-ebsco-java` | Docker Compose project name | +| **Module Configuration** | | | +| `ENV` | `folio` | Environment name | +| `MODULE_PORT` | `8081` | Module host port | +| `MODULE_REPLICAS` | `1` | Number of module instances to run | +| `DEBUG_PORT` | `5005` | Remote debugging port | +| **Database Configuration** | | | +| `DB_HOST` | `postgres` | PostgreSQL hostname | +| `DB_PORT` | `5432` | PostgreSQL port | +| `DB_DATABASE` | `modules` | Database name | +| `DB_USERNAME` | `folio_admin` | Database username | +| `DB_PASSWORD` | `folio_admin` | Database password | +| **pgAdmin Configuration** | | | +| `PGADMIN_DEFAULT_EMAIL` | `user@domain.com` | pgAdmin login email | +| `PGADMIN_DEFAULT_PASSWORD` | `admin` | pgAdmin login password | +| `PGADMIN_PORT` | `5050` | pgAdmin web interface port | +| **WireMock Configuration** | | | +| `OKAPI_URL` | `http://wiremock:8080` | Okapi URL for the module | +| `WIREMOCK_PORT` | `9130` | WireMock (Okapi mock) port | + +## 🚀 Services + +### PostgreSQL + +- **Purpose**: Primary database for module data +- **Version**: PostgreSQL 16 Alpine +- **Access**: localhost:5432 (configurable via `DB_PORT`) +- **Credentials**: See `DB_USERNAME` and `DB_PASSWORD` in `.env` +- **Database**: See `DB_DATABASE` in `.env` + +### pgAdmin + +- **Purpose**: Database administration interface +- **Access**: http://localhost:5050 (configurable via `PGADMIN_PORT`) +- **Login**: Use `PGADMIN_DEFAULT_EMAIL` and `PGADMIN_DEFAULT_PASSWORD` from `.env` + +### WireMock + +- **Purpose**: Mock Okapi and other FOLIO modules for testing +- **Access**: http://localhost:9130 (configurable via `WIREMOCK_PORT`) +- **Mappings**: Located in `src/test/resources/mappings` + +## 📖 Usage +### Starting the Environment + +```bash +# Build the module first +mvn clean package -DskipTests +``` +> **Note**: All further commands in this guide assume you are in the `docker/` directory. If you're at the project root, +> run `cd docker` first. + +```bash +# Start all services (infrastructure + module) +docker compose -f app-docker-compose.yml up -d +``` + +```bash +# Start only infrastructure services (for local development) +docker compose -f infra-docker-compose.yml up -d +``` + +```bash +# Start with build (if module code changed) +docker compose -f app-docker-compose.yml up -d --build +``` + +```bash +# Start specific service +docker compose -f infra-docker-compose.yml up -d postgres +``` + +### Stopping the Environment + +```bash +# Stop all services +docker compose -f app-docker-compose.yml down +``` + +```bash +# Stop infra services only +docker compose -f infra-docker-compose.yml down +``` + +```bash +# Stop and remove volumes (clean slate) +docker compose -f app-docker-compose.yml down -v +``` + +### Viewing Logs + +```bash +# All services +docker compose -f app-docker-compose.yml logs +``` + +```bash +# Specific service +docker compose -f app-docker-compose.yml logs mod-kb-ebsco-java +``` + +```bash +# Follow logs in real-time +docker compose -f app-docker-compose.yml logs -f mod-kb-ebsco-java +``` + +```bash +# Last 100 lines +docker compose -f app-docker-compose.yml logs --tail=100 mod-kb-ebsco-java +``` + +### Scaling the Module + +The module is configured with resource limits and deployment policies for production-like scaling: + +- **CPU Limits**: 0.5 CPU (max), 0.25 CPU (reserved) +- **Memory Limits**: 512M (max), 256M (reserved) +- **Restart Policy**: Automatic restart on failure + +```bash +# Scale to 3 instances +docker compose -f app-docker-compose.yml up -d --scale mod-kb-ebsco-java=3 +``` + +```bash +# Or modify MODULE_REPLICAS in .env and restart +echo "MODULE_REPLICAS=3" >> .env +docker compose -f app-docker-compose.yml up -d +``` + +### Cleanup and Reset + +```bash +# Complete cleanup (stops containers, removes volumes) +docker compose -f app-docker-compose.yml down -v +``` + +```bash +# Remove all Docker resources +docker compose -f app-docker-compose.yml down -v +docker volume prune -f +docker network prune -f +``` + +## 🛠️ Development + +### IntelliJ IDEA usage + +Run `docker compose -f infra-docker-compose.yml up -d` to start the infrastructure services. +Customize the `dev` profile if needed, or use the default values. +To activate this profile, set `application-dev.properties` in the `placeholderConfigurer` bean in the `ApplicationConfig` class. + +#### IntelliJ Application configuration using RestLauncher with the following settings: +- Run → Edit Configurations → + → Application +- Main class: `org.folio.rest.RestLauncher` +- Program arguments: `org.folio.rest.RestVerticle` +- Environment variables: +```bash +DB_HOST=localhost +DB_PORT=5432 +DB_DATABASE=modules +DB_USERNAME=folio_admin +DB_PASSWORD=folio_admin +``` +### Building the Module + +It's expected that the module is packaged to jar before building the Docker image. Use `mvn clean package` to build the +jar. + +```bash +# Build only the module image +docker compose -f app-docker-compose.yml build mod-kb-ebsco-java +``` + +```bash +# Build with no cache +docker compose -f app-docker-compose.yml build --no-cache mod-kb-ebsco-java +``` + +### Connecting to Services + +```bash +# Connect to PostgreSQL +docker compose -f app-docker-compose.yml exec postgres psql -U folio_admin -d modules +``` + +```bash +# Check PostgreSQL health +docker compose -f infra-docker-compose.yml exec postgres pg_isready -U folio_admin +``` + +```bash +# Connect to module container +docker compose -f app-docker-compose.yml exec mod-kb-ebsco-java sh +``` diff --git a/docker/app-docker-compose.yml b/docker/app-docker-compose.yml new file mode 100644 index 00000000..36172bdd --- /dev/null +++ b/docker/app-docker-compose.yml @@ -0,0 +1,42 @@ +# Full application stack for mmod-kb-ebsco-java (infrastructure + module) +# This includes all infrastructure services and the mod-kb-ebsco-java module itself + +include: + - infra-docker-compose.yml + +services: + mod-kb-ebsco-java: + image: dev.folio/mod-kb-ebsco-java + build: + context: ../ + dockerfile: Dockerfile + ports: + - "${MODULE_PORT}:8081" + - "${DEBUG_PORT}:5005" + environment: + ENV: ${ENV} + DB_USERNAME: ${DB_USERNAME} + DB_PORT: ${DB_PORT} + DB_HOST: ${DB_HOST} + DB_DATABASE: ${DB_DATABASE} + DB_PASSWORD: ${DB_PASSWORD} + JAVA_OPTIONS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" + depends_on: + - postgres + - wiremock + networks: + - mod-kb-ebsco-java-local + deploy: + replicas: ${MODULE_REPLICAS:-1} + restart_policy: + condition: on-failure + update_config: + parallelism: 1 + delay: 10s + resources: + limits: + cpus: "0.5" + memory: "512M" + reservations: + cpus: "0.25" + memory: "256M" diff --git a/docker/docker-compose.yml b/docker/infra-docker-compose.yml similarity index 55% rename from docker/docker-compose.yml rename to docker/infra-docker-compose.yml index 3932495f..d1951f02 100644 --- a/docker/docker-compose.yml +++ b/docker/infra-docker-compose.yml @@ -1,10 +1,12 @@ -version: "3.9" +# Infrastructure services for mod-kb-ebsco-java +# This file contains all infrastructure dependencies (database, storage, mocks) +# It can be used standalone for local development or included in app-docker-compose.yml services: postgres: - image: postgres:12-alpine + image: postgres:16-alpine ports: - - "5432:5432" + - ${DB_PORT}:5432 volumes: - postgres-data:/data/postgres environment: @@ -16,7 +18,7 @@ services: - mod-kb-ebsco-java-local pgadmin: - image: dpage/pgadmin4:6.7 + image: dpage/pgadmin4:latest ports: - ${PGADMIN_PORT}:80 volumes: @@ -28,24 +30,13 @@ services: networks: - mod-kb-ebsco-java-local - mod-kb-ebsco-java: - image: dev.folio/mod-kb-ebsco-java - build: - context: ..\ - dockerfile: Dockerfile + wiremock: + image: wiremock/wiremock:latest ports: - - "8081:8081" - - "5005:5005" - environment: - ENV: ${ENV} - DB_USERNAME: ${DB_USERNAME} - DB_PORT: ${DB_PORT} - DB_HOST: ${DB_HOST} - DB_DATABASE: ${DB_DATABASE} - DB_PASSWORD: ${DB_PASSWORD} - JAVA_OPTIONS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:${DEBUG_PORT}" - depends_on: - - "postgres" + - ${WIREMOCK_PORT}:8080 + volumes: + - ../src/test/resources/mappings:/home/wiremock/mappings + entrypoint: [ "/docker-entrypoint.sh", "--global-response-templating", "--disable-gzip", "--verbose" ] networks: - mod-kb-ebsco-java-local @@ -54,7 +45,5 @@ networks: driver: "bridge" volumes: - pgadmin-data: - driver: "local" postgres-data: - driver: "local" + pgadmin-data: diff --git a/src/main/resources/application-dev.properties b/src/main/resources/application-dev.properties new file mode 100644 index 00000000..62431c10 --- /dev/null +++ b/src/main/resources/application-dev.properties @@ -0,0 +1,53 @@ +# Development profile for local development +# Activate this profile: set application-dev.properties to the placeholderConfigurer bean in the ApplicationConfig class + +db.exception.translator.name=postgresql + +# Possible values are TransactionLoadServiceFacade, DefaultLoadServiceFacade +# Qualifier of a bean that implements LoadServiceFacade interface. +holdings.load.implementation.qualifier=defaultLoadServiceFacade +holdings.load.retry.count=3 +holdings.load.retry.delay=10800000 +holdings.page.size=2500 +holdings.page.size.min=100 +holdings.page.retry.count=3 +holdings.page.retry.delay=900000 +holdings.report.status.check.delay=120000 +holdings.report.status.retry.count=30 +holdings.snapshot.refresh.period=86400000 +holdings.snapshot.retry.count=3 +holdings.snapshot.retry.delay=10800000 +holdings.status.audit.expiration.period=2592000000 +holdings.status.check.delay=300000 +holdings.status.retry.count=20 +holdings.timeout=3600000 + +# Credentials properties +kb.ebsco.credentials.name.length.max=255 +kb.ebsco.credentials.url.default=https://api.ebsco.io +kb.ebsco.credentials.access.types.limit=15 +kb.ebsco.credentials.access.types.name.length.max=75 +kb.ebsco.credentials.access.types.description.length.max=150 + +# Usage Consolidation properties +kb.ebsco.uc.auth.url=https://apis.ebsco.com + +# Cache properties +uc.token.cache.expire=3600 +uc.title-package.cache.expire=86400 +uc.title-package.cache.enable=false +currencies.cache.expire=86400 +configuration.cache.expire=120 +package.cache.expire=86400 +resource.cache.expire=86400 +title.cache.expire=43200 +vendor.cache.expire=86400 +vendor.id.cache.expire=600 + +# Custom labels properties +kb.ebsco.custom.labels.label.length.max=200 +kb.ebsco.custom.labels.value.length.max=500 + +# HoldingsIQ search type properties +kb.ebsco.search-type.titles=advanced +kb.ebsco.search-type.packages=advanced