Skip to content

Commit 0fbe025

Browse files
viacheslavkolviacheslavkol
committed
chore: Improve docker compose for local development
- add compose file for app - add compose file for ingrastructure - add env and pgadmin servers files - add readme file for docker compose testing Implements: MODNOTES-280
1 parent 8f84702 commit 0fbe025

7 files changed

Lines changed: 636 additions & 0 deletions

File tree

‎docker/.env‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Project name for Docker Compose
2+
COMPOSE_PROJECT_NAME=folio-mod-notes
3+
4+
# Module configuration
5+
MODULE_PORT=8081
6+
MODULE_REPLICAS=1
7+
DEBUG_PORT=5005
8+
9+
# PostgreSQL configuration
10+
DB_HOST=postgres
11+
DB_PORT=5432
12+
DB_DATABASE=modules
13+
DB_USERNAME=folio_admin
14+
DB_PASSWORD=folio_admin
15+
16+
# PgAdmin configuration
17+
PGADMIN_PORT=5050
18+
PGADMIN_DEFAULT_EMAIL=user@domain.com
19+
PGADMIN_DEFAULT_PASSWORD=admin
20+
21+
# WireMock (Okapi mock) configuration
22+
WIREMOCK_PORT=9130
23+
OKAPI_URL=http://wiremock:8080
24+

‎docker/README.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
# 🐳 Docker Compose Setup for mod-notes
2+
3+
Local development environment for mod-notes using Docker Compose.
4+
5+
## 📋 Prerequisites
6+
7+
- Docker and Docker Compose V2+
8+
- Java 21+ (for local development mode)
9+
- Maven 3.8+ (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, pgAdmin, WireMock)
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+
### Key Environment Variables
23+
24+
| Variable | Description | Default |
25+
|---------------------------|-------------------------------|------------------------|
26+
| `MODULE_REPLICAS` | Number of module instances | `1` |
27+
| `MODULE_PORT` | Module host port | `8081` |
28+
| `DEBUG_PORT` | Remote debugging port | `5005` |
29+
| `DB_HOST` | PostgreSQL hostname | `postgres` |
30+
| `DB_PORT` | PostgreSQL port | `5432` |
31+
| `DB_DATABASE` | Database name | `modules` |
32+
| `DB_USERNAME` | Database user | `folio_admin` |
33+
| `DB_PASSWORD` | Database password | `folio_admin` |
34+
| `PGADMIN_PORT` | PgAdmin port | `5050` |
35+
| `WIREMOCK_PORT` | WireMock (Okapi mock) port | `9130` |
36+
| `OKAPI_URL` | Okapi URL for the module | `http://wiremock:8080` |
37+
38+
## 🚀 Services
39+
40+
### PostgreSQL
41+
- **Purpose**: Primary database for module data
42+
- **Version**: PostgreSQL 16 Alpine
43+
- **Access**: localhost:5432 (configurable via `DB_PORT`)
44+
- **Credentials**: See `DB_USERNAME` and `DB_PASSWORD` in `.env`
45+
- **Database**: See `DB_DATABASE` in `.env`
46+
47+
### pgAdmin
48+
- **Purpose**: Database administration interface
49+
- **Access**: http://localhost:5050 (configurable via `PGADMIN_PORT`)
50+
- **Login**: Use `PGADMIN_DEFAULT_EMAIL` and `PGADMIN_DEFAULT_PASSWORD` from `.env`
51+
52+
### WireMock
53+
- **Purpose**: Mock Okapi and other FOLIO modules for local testing
54+
- **Access**: http://localhost:9130 (configurable via `WIREMOCK_PORT`)
55+
- **Mappings**: Located in `src/test/resources/mappings`
56+
57+
## 📖 Usage
58+
59+
> **Note**: All commands in this guide assume you are in the `docker/` directory. If you're at the project root, run `cd docker` first.
60+
61+
### Starting the Environment
62+
63+
```bash
64+
# Build the module first
65+
mvn -f ../pom.xml clean package -DskipTests
66+
67+
# Start all services (infrastructure + module)
68+
docker compose -f app-docker-compose.yml up -d
69+
```
70+
71+
```bash
72+
# Start only infrastructure services (for local development)
73+
docker compose -f infra-docker-compose.yml up -d
74+
```
75+
76+
```bash
77+
# Start with build (if module code changed)
78+
docker compose -f app-docker-compose.yml up -d --build
79+
```
80+
81+
```bash
82+
# Start specific service
83+
docker compose -f infra-docker-compose.yml up -d postgres
84+
```
85+
86+
### Stopping the Environment
87+
88+
```bash
89+
# Stop all services
90+
docker compose -f app-docker-compose.yml down
91+
```
92+
93+
```bash
94+
# Stop infra services only
95+
docker compose -f infra-docker-compose.yml down
96+
```
97+
98+
```bash
99+
# Stop and remove volumes (clean slate)
100+
docker compose -f app-docker-compose.yml down -v
101+
```
102+
103+
### Viewing Logs
104+
105+
```bash
106+
# All services
107+
docker compose -f app-docker-compose.yml logs
108+
```
109+
110+
```bash
111+
# Specific service
112+
docker compose -f app-docker-compose.yml logs mod-notes
113+
```
114+
115+
```bash
116+
# Follow logs in real-time
117+
docker compose -f app-docker-compose.yml logs -f mod-notes
118+
```
119+
120+
```bash
121+
# Last 100 lines
122+
docker compose -f app-docker-compose.yml logs --tail=100 mod-notes
123+
```
124+
125+
### Scaling the Module
126+
127+
The module is configured with resource limits and deployment policies for production-like scaling:
128+
129+
- **CPU Limits**: 1.0 CPU (max), 0.5 CPU (reserved)
130+
- **Memory Limits**: 512M (max), 256M (reserved)
131+
- **Restart Policy**: Automatic restart on failure
132+
- **Update Strategy**: Rolling updates with 1 instance at a time, 10s delay
133+
134+
```bash
135+
# Scale to 3 instances
136+
docker compose -f app-docker-compose.yml up -d --scale mod-notes=3
137+
```
138+
139+
```bash
140+
# Or modify MODULE_REPLICAS in .env and restart
141+
echo "MODULE_REPLICAS=3" >> .env
142+
docker compose -f app-docker-compose.yml up -d
143+
```
144+
145+
### Cleanup and Reset
146+
147+
```bash
148+
# Complete cleanup (stops containers, removes volumes)
149+
docker compose -f app-docker-compose.yml down -v
150+
```
151+
152+
```bash
153+
# Remove all Docker resources
154+
docker compose -f app-docker-compose.yml down -v
155+
docker volume prune -f
156+
docker network prune -f
157+
```
158+
159+
## 🔧 Development Workflows
160+
161+
### Workflow 1: Full Docker Stack
162+
Run everything in Docker, including the module.
163+
164+
```bash
165+
# Build the module
166+
mvn -f ../pom.xml clean package -DskipTests
167+
168+
# Start all services
169+
docker compose -f app-docker-compose.yml up -d
170+
171+
# View logs
172+
docker compose -f app-docker-compose.yml logs -f mod-notes
173+
```
174+
175+
**Use Case**: Testing the full deployment, simulating production environment, scaling tests.
176+
177+
### Workflow 2: Infrastructure Only + IDE
178+
Run infrastructure in Docker, develop the module in your IDE.
179+
180+
```bash
181+
# Start infrastructure
182+
docker compose -f infra-docker-compose.yml up -d
183+
184+
# Run module from IDE or command line
185+
mvn -f ../pom.xml spring-boot:run
186+
```
187+
188+
**Use Case**: Active development with hot reload, debugging in IDE, faster iteration cycles.
189+
190+
### Workflow 3: Spring Boot Docker Compose Integration
191+
Let Spring Boot manage Docker Compose automatically (recommended for rapid development).
192+
193+
```bash
194+
# Run with dev profile (starts infrastructure automatically)
195+
mvn -f ../pom.xml spring-boot:run -Dspring-boot.run.profiles=dev
196+
```
197+
198+
The `dev` profile is configured to:
199+
- Start services from `docker/infra-docker-compose.yml` automatically
200+
- Connect to services via localhost ports (PostgreSQL: 5432, WireMock: 9130)
201+
- Keep containers running after the application stops for faster subsequent startups
202+
203+
**Use Case**: Quickest way to start development — no manual Docker commands needed.
204+
205+
### Workflow 4: Spring Boot DevTools
206+
For rapid development with automatic restart on code changes.
207+
208+
```bash
209+
# Start infrastructure
210+
docker compose -f infra-docker-compose.yml up -d
211+
212+
# Run with devtools (automatic restart on code changes)
213+
mvn -f ../pom.xml spring-boot:run
214+
215+
# Make code changes — application will automatically restart
216+
```
217+
218+
**Use Case**: Continuous development with automatic reload, live code updates, rapid feedback loop.
219+
220+
## 🛠️ Common Tasks
221+
222+
### Building the Module
223+
224+
```bash
225+
# Clean build (skip tests)
226+
mvn -f ../pom.xml clean package -DskipTests
227+
```
228+
229+
```bash
230+
# Build with tests
231+
mvn -f ../pom.xml clean package
232+
```
233+
234+
### Tenant Setup
235+
236+
After starting the module, register a tenant by calling the `/_/tenant` API:
237+
238+
```bash
239+
curl -X POST http://localhost:8081/_/tenant \
240+
-H "Content-Type: application/json" \
241+
-H "X-Okapi-Tenant: diku" \
242+
-H "X-Okapi-Url: http://localhost:9130" \
243+
-d '{"module_to": "mod-notes-8.0.0-SNAPSHOT", "parameters": [{"key": "loadReference", "value": "true"}]}'
244+
```
245+
246+
> **Note**: Adjust `module_to` version to match the currently running module version.
247+
248+
### Accessing Services
249+
250+
```bash
251+
# PostgreSQL CLI
252+
docker compose -f infra-docker-compose.yml exec postgres psql -U folio_admin -d modules
253+
```
254+
255+
```bash
256+
# View database tables
257+
docker compose -f infra-docker-compose.yml exec postgres psql -U folio_admin -d modules -c "\dt"
258+
```
259+
260+
```bash
261+
# Check PostgreSQL health
262+
docker compose -f infra-docker-compose.yml exec postgres pg_isready -U folio_admin
263+
```
264+
265+
### Rebuilding the Module
266+
267+
```bash
268+
# Rebuild and restart the module
269+
mvn -f ../pom.xml clean package -DskipTests
270+
docker compose -f app-docker-compose.yml up -d --build mod-notes
271+
```
272+
273+
```bash
274+
# Force rebuild without cache
275+
docker compose -f app-docker-compose.yml build --no-cache mod-notes
276+
docker compose -f app-docker-compose.yml up -d mod-notes
277+
```
278+
279+
## 🐛 Troubleshooting
280+
281+
### Port Conflicts
282+
283+
If you encounter port conflicts, modify the ports in `.env`:
284+
285+
```bash
286+
# Example: Change module port to 8082
287+
MODULE_PORT=8082
288+
```
289+
290+
Then restart the services:
291+
292+
```bash
293+
docker compose -f app-docker-compose.yml up -d
294+
```
295+
296+
### Container Health Issues
297+
298+
```bash
299+
# Check container status
300+
docker compose -f app-docker-compose.yml ps
301+
302+
# Check specific container logs
303+
docker compose -f app-docker-compose.yml logs mod-notes
304+
305+
# Restart a specific service
306+
docker compose -f app-docker-compose.yml restart mod-notes
307+
```
308+
309+
### Database Connection Issues
310+
311+
```bash
312+
# Verify PostgreSQL is running
313+
docker compose -f infra-docker-compose.yml ps postgres
314+
315+
# Check PostgreSQL logs
316+
docker compose -f infra-docker-compose.yml logs postgres
317+
318+
# Test database connection
319+
docker compose -f infra-docker-compose.yml exec postgres psql -U folio_admin -d modules -c "SELECT 1"
320+
```
321+
322+
**`FATAL: database "modules" does not exist`** — PostgreSQL only creates the database defined in `POSTGRES_DB` on the very first startup with an empty data directory. If the `postgres-data` volume already existed from a previous run (with different settings), the init is skipped. Fix by recreating the volume:
323+
324+
```bash
325+
docker compose -f infra-docker-compose.yml stop postgres pgadmin
326+
docker compose -f infra-docker-compose.yml rm -f postgres pgadmin
327+
docker volume rm folio-mod-notes_postgres-data
328+
docker compose -f infra-docker-compose.yml up -d postgres pgadmin
329+
```
330+
331+
### Clean Start
332+
333+
If you need to completely reset the environment:
334+
335+
```bash
336+
# Stop and remove everything
337+
docker compose -f app-docker-compose.yml down -v
338+
339+
# Remove any orphaned containers
340+
docker container prune -f
341+
342+
# Remove unused networks
343+
docker network prune -f
344+
345+
# Start fresh
346+
mvn -f ../pom.xml clean package -DskipTests
347+
docker compose -f app-docker-compose.yml up -d --build
348+
```
349+
350+
## 📚 Additional Resources
351+
352+
- [Docker Compose Documentation](https://docs.docker.com/compose/)
353+
- [Spring Boot Docker Compose Support](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.docker-compose)
354+
- [mod-notes Documentation](../README.md)
355+
356+
## 💡 Tips
357+
358+
- Use **Workflow 3** (Spring Boot Docker Compose) for the fastest development experience
359+
- Keep infrastructure running between development sessions to save startup time
360+
- Use **Workflow 1** (Full Docker Stack) when testing deployment or scaling scenarios
361+
- Use `docker compose -f infra-docker-compose.yml logs -f` to monitor all infrastructure services
362+
- pgAdmin provides a helpful web interface for inspecting the database at http://localhost:5050
363+

0 commit comments

Comments
 (0)