Skip to content

Commit 0470f77

Browse files
SvitlanaKovalova1SvitlanaKovalova1
committed
chore: Improve Docker Compose setup for local development
1 parent 465a7cc commit 0470f77

6 files changed

Lines changed: 346 additions & 28 deletions

File tree

‎NEWS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
* Adjust logging to hide sensitive data ([MODKBEKBJ-776](https://folio-org.atlassian.net/browse/MODKBEKBJ-776))
1818
* Refactor code to comply with Checkstyle method length limit (max 25 lines) ([MODKBEKBJ-808](https://folio-org.atlassian.net/browse/MODKBEKBJ-808))
1919
* Use GitHub workflow for CI/CD ([MODKBEKBJ-817](https://folio-org.atlassian.net/browse/MODKBEKBJ-817))
20+
* Improve Docker Compose setup for local development ([MODKBEKBJ-805](https://folio-org.atlassian.net/browse/MODKBEKBJ-805))
2021

2122
### Dependencies
2223
* Bump `LIB_NAME` from `OLD_VERSION` to `NEW_VERSION`

‎docker/.env‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,25 @@
11
COMPOSE_PROJECT_NAME=folio-mod-kb-ebsco-java
2+
3+
# Environment name
4+
ENV=folio
5+
6+
# Module configuration
7+
MODULE_PORT=8081
8+
MODULE_REPLICAS=1
9+
DEBUG_PORT=5005
10+
11+
# PostgreSQL configuration
212
DB_HOST=postgres
313
DB_PORT=5432
4-
DB_DATABASE=okapi_modules
14+
DB_DATABASE=modules
515
DB_USERNAME=folio_admin
616
DB_PASSWORD=folio_admin
17+
18+
# PgAdmin configuration
19+
PGADMIN_PORT=5050
720
PGADMIN_DEFAULT_EMAIL=user@domain.com
821
PGADMIN_DEFAULT_PASSWORD=admin
9-
PGADMIN_PORT=5050
10-
ENV=folio
11-
DEBUG_PORT=5005
1222

23+
# WireMock (Okapi mock) configuration
24+
WIREMOCK_PORT=9130
25+
OKAPI_URL=http://wiremock:8080

‎docker/README.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# 🐳 Docker Compose Setup for mod-kb-ebsco-java
2+
3+
Local development environment for mod-kb-ebsco-java using Docker Compose.
4+
5+
## 📋 Prerequisites
6+
7+
- Docker and Docker Compose V2+
8+
- Java 21+ (for local development mode)
9+
- Maven 3.6+ (for building the module)
10+
11+
## 🏗️ Architecture
12+
13+
Two compose files provide flexible development workflows:
14+
15+
- **`infra-docker-compose.yml`**: Infrastructure services only (PostgreSQL, WireMock, etc.)
16+
- **`app-docker-compose.yml`**: Full stack including the module (uses `include` to incorporate infra services)
17+
18+
## ⚙️ Configuration
19+
20+
Configuration is managed via the `.env` file in this directory.
21+
22+
### Environment Variables
23+
24+
| Variable | Default Value | Description |
25+
|----------------------------|---------------------------|-----------------------------------|
26+
| `COMPOSE_PROJECT_NAME` | `folio-mod-kb-ebsco-java` | Docker Compose project name |
27+
| **Module Configuration** | | |
28+
| `ENV` | `folio` | Environment name |
29+
| `MODULE_PORT` | `8081` | Module host port |
30+
| `MODULE_REPLICAS` | `1` | Number of module instances to run |
31+
| `DEBUG_PORT` | `5005` | Remote debugging port |
32+
| **Database Configuration** | | |
33+
| `DB_HOST` | `postgres` | PostgreSQL hostname |
34+
| `DB_PORT` | `5432` | PostgreSQL port |
35+
| `DB_DATABASE` | `modules` | Database name |
36+
| `DB_USERNAME` | `folio_admin` | Database username |
37+
| `DB_PASSWORD` | `folio_admin` | Database password |
38+
| **pgAdmin Configuration** | | |
39+
| `PGADMIN_DEFAULT_EMAIL` | `user@domain.com` | pgAdmin login email |
40+
| `PGADMIN_DEFAULT_PASSWORD` | `admin` | pgAdmin login password |
41+
| `PGADMIN_PORT` | `5050` | pgAdmin web interface port |
42+
| **WireMock Configuration** | | |
43+
| `OKAPI_URL` | `http://wiremock:8080` | Okapi URL for the module |
44+
| `WIREMOCK_PORT` | `9130` | WireMock (Okapi mock) port |
45+
46+
## 🚀 Services
47+
48+
### PostgreSQL
49+
50+
- **Purpose**: Primary database for module data
51+
- **Version**: PostgreSQL 16 Alpine
52+
- **Access**: localhost:5432 (configurable via `DB_PORT`)
53+
- **Credentials**: See `DB_USERNAME` and `DB_PASSWORD` in `.env`
54+
- **Database**: See `DB_DATABASE` in `.env`
55+
56+
### pgAdmin
57+
58+
- **Purpose**: Database administration interface
59+
- **Access**: http://localhost:5050 (configurable via `PGADMIN_PORT`)
60+
- **Login**: Use `PGADMIN_DEFAULT_EMAIL` and `PGADMIN_DEFAULT_PASSWORD` from `.env`
61+
62+
### WireMock
63+
64+
- **Purpose**: Mock Okapi and other FOLIO modules for testing
65+
- **Access**: http://localhost:9130 (configurable via `WIREMOCK_PORT`)
66+
- **Mappings**: Located in `src/test/resources/mappings`
67+
68+
## 📖 Usage
69+
### Starting the Environment
70+
71+
```bash
72+
# Build the module first
73+
mvn clean package -DskipTests
74+
```
75+
> **Note**: All further commands in this guide assume you are in the `docker/` directory. If you're at the project root,
76+
> run `cd docker` first.
77+
78+
```bash
79+
# Start all services (infrastructure + module)
80+
docker compose -f app-docker-compose.yml up -d
81+
```
82+
83+
```bash
84+
# Start only infrastructure services (for local development)
85+
docker compose -f infra-docker-compose.yml up -d
86+
```
87+
88+
```bash
89+
# Start with build (if module code changed)
90+
docker compose -f app-docker-compose.yml up -d --build
91+
```
92+
93+
```bash
94+
# Start specific service
95+
docker compose -f infra-docker-compose.yml up -d postgres
96+
```
97+
98+
### Stopping the Environment
99+
100+
```bash
101+
# Stop all services
102+
docker compose -f app-docker-compose.yml down
103+
```
104+
105+
```bash
106+
# Stop infra services only
107+
docker compose -f infra-docker-compose.yml down
108+
```
109+
110+
```bash
111+
# Stop and remove volumes (clean slate)
112+
docker compose -f app-docker-compose.yml down -v
113+
```
114+
115+
### Viewing Logs
116+
117+
```bash
118+
# All services
119+
docker compose -f app-docker-compose.yml logs
120+
```
121+
122+
```bash
123+
# Specific service
124+
docker compose -f app-docker-compose.yml logs mod-kb-ebsco-java
125+
```
126+
127+
```bash
128+
# Follow logs in real-time
129+
docker compose -f app-docker-compose.yml logs -f mod-kb-ebsco-java
130+
```
131+
132+
```bash
133+
# Last 100 lines
134+
docker compose -f app-docker-compose.yml logs --tail=100 mod-kb-ebsco-java
135+
```
136+
137+
### Scaling the Module
138+
139+
The module is configured with resource limits and deployment policies for production-like scaling:
140+
141+
- **CPU Limits**: 0.5 CPU (max), 0.25 CPU (reserved)
142+
- **Memory Limits**: 512M (max), 256M (reserved)
143+
- **Restart Policy**: Automatic restart on failure
144+
145+
```bash
146+
# Scale to 3 instances
147+
docker compose -f app-docker-compose.yml up -d --scale mod-kb-ebsco-java=3
148+
```
149+
150+
```bash
151+
# Or modify MODULE_REPLICAS in .env and restart
152+
echo "MODULE_REPLICAS=3" >> .env
153+
docker compose -f app-docker-compose.yml up -d
154+
```
155+
156+
### Cleanup and Reset
157+
158+
```bash
159+
# Complete cleanup (stops containers, removes volumes)
160+
docker compose -f app-docker-compose.yml down -v
161+
```
162+
163+
```bash
164+
# Remove all Docker resources
165+
docker compose -f app-docker-compose.yml down -v
166+
docker volume prune -f
167+
docker network prune -f
168+
```
169+
170+
## 🛠️ Development
171+
172+
### IntelliJ IDEA usage
173+
174+
Run `docker compose -f infra-docker-compose.yml up -d` to start the infrastructure services.
175+
Customize the `dev` profile if needed, or use the default values.
176+
To activate this profile, set `application-dev.properties` in the `placeholderConfigurer` bean in the `ApplicationConfig` class.
177+
178+
#### IntelliJ Application configuration using RestLauncher with the following settings:
179+
- Run → Edit Configurations → + → Application
180+
- Main class: `org.folio.rest.RestLauncher`
181+
- Program arguments: `org.folio.rest.RestVerticle`
182+
- Environment variables:
183+
```bash
184+
DB_HOST=localhost
185+
DB_PORT=5432
186+
DB_DATABASE=modules
187+
DB_USERNAME=folio_admin
188+
DB_PASSWORD=folio_admin
189+
```
190+
### Building the Module
191+
192+
It's expected that the module is packaged to jar before building the Docker image. Use `mvn clean package` to build the
193+
jar.
194+
195+
```bash
196+
# Build only the module image
197+
docker compose -f app-docker-compose.yml build mod-kb-ebsco-java
198+
```
199+
200+
```bash
201+
# Build with no cache
202+
docker compose -f app-docker-compose.yml build --no-cache mod-kb-ebsco-java
203+
```
204+
205+
### Connecting to Services
206+
207+
```bash
208+
# Connect to PostgreSQL
209+
docker compose -f app-docker-compose.yml exec postgres psql -U folio_admin -d modules
210+
```
211+
212+
```bash
213+
# Check PostgreSQL health
214+
docker compose -f infra-docker-compose.yml exec postgres pg_isready -U folio_admin
215+
```
216+
217+
```bash
218+
# Connect to module container
219+
docker compose -f app-docker-compose.yml exec mod-kb-ebsco-java sh
220+
```

‎docker/app-docker-compose.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Full application stack for mmod-kb-ebsco-java (infrastructure + module)
2+
# This includes all infrastructure services and the mod-kb-ebsco-java module itself
3+
4+
include:
5+
- infra-docker-compose.yml
6+
7+
services:
8+
mod-kb-ebsco-java:
9+
image: dev.folio/mod-kb-ebsco-java
10+
build:
11+
context: ../
12+
dockerfile: Dockerfile
13+
ports:
14+
- "${MODULE_PORT}:8081"
15+
- "${DEBUG_PORT}:5005"
16+
environment:
17+
ENV: ${ENV}
18+
DB_USERNAME: ${DB_USERNAME}
19+
DB_PORT: ${DB_PORT}
20+
DB_HOST: ${DB_HOST}
21+
DB_DATABASE: ${DB_DATABASE}
22+
DB_PASSWORD: ${DB_PASSWORD}
23+
JAVA_OPTIONS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
24+
depends_on:
25+
- postgres
26+
- wiremock
27+
networks:
28+
- mod-kb-ebsco-java-local
29+
deploy:
30+
replicas: ${MODULE_REPLICAS:-1}
31+
restart_policy:
32+
condition: on-failure
33+
update_config:
34+
parallelism: 1
35+
delay: 10s
36+
resources:
37+
limits:
38+
cpus: "0.5"
39+
memory: "512M"
40+
reservations:
41+
cpus: "0.25"
42+
memory: "256M"

docker/docker-compose.yml renamed to docker/infra-docker-compose.yml

Lines changed: 13 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
version: "3.9"
1+
# Infrastructure services for mod-kb-ebsco-java
2+
# This file contains all infrastructure dependencies (database, storage, mocks)
3+
# It can be used standalone for local development or included in app-docker-compose.yml
24

35
services:
46
postgres:
5-
image: postgres:12-alpine
7+
image: postgres:16-alpine
68
ports:
7-
- "5432:5432"
9+
- ${DB_PORT}:5432
810
volumes:
911
- postgres-data:/data/postgres
1012
environment:
@@ -16,7 +18,7 @@ services:
1618
- mod-kb-ebsco-java-local
1719

1820
pgadmin:
19-
image: dpage/pgadmin4:6.7
21+
image: dpage/pgadmin4:latest
2022
ports:
2123
- ${PGADMIN_PORT}:80
2224
volumes:
@@ -28,24 +30,13 @@ services:
2830
networks:
2931
- mod-kb-ebsco-java-local
3032

31-
mod-kb-ebsco-java:
32-
image: dev.folio/mod-kb-ebsco-java
33-
build:
34-
context: ..\
35-
dockerfile: Dockerfile
33+
wiremock:
34+
image: wiremock/wiremock:latest
3635
ports:
37-
- "8081:8081"
38-
- "5005:5005"
39-
environment:
40-
ENV: ${ENV}
41-
DB_USERNAME: ${DB_USERNAME}
42-
DB_PORT: ${DB_PORT}
43-
DB_HOST: ${DB_HOST}
44-
DB_DATABASE: ${DB_DATABASE}
45-
DB_PASSWORD: ${DB_PASSWORD}
46-
JAVA_OPTIONS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:${DEBUG_PORT}"
47-
depends_on:
48-
- "postgres"
36+
- ${WIREMOCK_PORT}:8080
37+
volumes:
38+
- ../src/test/resources/mappings:/home/wiremock/mappings
39+
entrypoint: [ "/docker-entrypoint.sh", "--global-response-templating", "--disable-gzip", "--verbose" ]
4940
networks:
5041
- mod-kb-ebsco-java-local
5142

@@ -54,7 +45,5 @@ networks:
5445
driver: "bridge"
5546

5647
volumes:
57-
pgadmin-data:
58-
driver: "local"
5948
postgres-data:
60-
driver: "local"
49+
pgadmin-data:

0 commit comments

Comments
 (0)