folio-org · SvitlanaKovalova1 · Mar 13, 2026 · Mar 13, 2026
@@ -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`

@@ -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
@@ -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
+```
@@ -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"
@@ -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: