setup coverate report generation
This commit is contained in:
400
DOCKER_COMPOSE_GUIDE.md
Normal file
400
DOCKER_COMPOSE_GUIDE.md
Normal file
@ -0,0 +1,400 @@
|
||||
# Docker Compose Patterns - Quick Guide
|
||||
|
||||
This guide provides a focused reference for all Docker Compose patterns used in this project.
|
||||
|
||||
## Overview
|
||||
|
||||
This project uses **three Docker Compose files** for different purposes:
|
||||
|
||||
```
|
||||
docker-compose.yml ← Start application server
|
||||
docker-compose.test.yml ← Run unit tests
|
||||
docker-compose.coverage.yml ← Generate coverage reports
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: Application Server
|
||||
|
||||
**File**: `docker-compose.yml`
|
||||
**Purpose**: Deploy JAX-WS application to Tomcat
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Start server
|
||||
docker-compose up -d
|
||||
|
||||
# Start with build
|
||||
docker-compose up -d --build
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Stop server
|
||||
docker-compose down
|
||||
|
||||
# Restart
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
### What Happens
|
||||
|
||||
1. Builds Docker image (3 stages):
|
||||
- Stage 1: Run unit tests
|
||||
- Stage 2: Build WAR file
|
||||
- Stage 3: Deploy to Tomcat
|
||||
2. Starts Tomcat on port 8080
|
||||
3. Creates/persists SQLite database
|
||||
|
||||
### Access
|
||||
|
||||
- Hello World: http://localhost:8080/jaxws-hello-world/hello?wsdl
|
||||
- Loan Service: http://localhost:8080/jaxws-hello-world/loan?wsdl
|
||||
- Tomcat Manager: http://localhost:8080/manager (admin/admin123)
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Run Unit Tests
|
||||
|
||||
**File**: `docker-compose.test.yml`
|
||||
**Purpose**: Execute JUnit tests
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
docker-compose -f docker-compose.test.yml up --build
|
||||
|
||||
# View test output
|
||||
docker-compose -f docker-compose.test.yml logs
|
||||
|
||||
# Clean up
|
||||
docker-compose -f docker-compose.test.yml down
|
||||
|
||||
# One-liner (run and clean)
|
||||
docker-compose -f docker-compose.test.yml up --build && docker-compose -f docker-compose.test.yml down
|
||||
```
|
||||
|
||||
### Convenience Scripts
|
||||
|
||||
**Windows:**
|
||||
```cmd
|
||||
run-tests.bat
|
||||
```
|
||||
|
||||
**Linux/Mac:**
|
||||
```bash
|
||||
./run-tests.sh
|
||||
```
|
||||
|
||||
### What Happens
|
||||
|
||||
1. Builds test environment
|
||||
2. Runs `mvn test`
|
||||
3. Executes all *Test.java files
|
||||
4. Exports results to `./target/surefire-reports/`
|
||||
5. Generates JaCoCo coverage data
|
||||
|
||||
### Output
|
||||
|
||||
**Console:**
|
||||
```
|
||||
Tests run: 10, Failures: 0, Errors: 0, Skipped: 0
|
||||
BUILD SUCCESS
|
||||
```
|
||||
|
||||
**Files:**
|
||||
- `./target/surefire-reports/` - Test reports (text & XML)
|
||||
- `./target/jacoco.exec` - Coverage data
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Generate Code Coverage
|
||||
|
||||
**File**: `docker-compose.coverage.yml`
|
||||
**Purpose**: Generate JaCoCo coverage reports
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Generate coverage
|
||||
docker-compose -f docker-compose.coverage.yml up --build
|
||||
|
||||
# View logs
|
||||
docker-compose -f docker-compose.coverage.yml logs
|
||||
|
||||
# Clean up
|
||||
docker-compose -f docker-compose.coverage.yml down
|
||||
|
||||
# One-liner (generate and clean)
|
||||
docker-compose -f docker-compose.coverage.yml up --build && docker-compose -f docker-compose.coverage.yml down
|
||||
```
|
||||
|
||||
### Convenience Scripts
|
||||
|
||||
**Windows:**
|
||||
```cmd
|
||||
run-coverage.bat
|
||||
```
|
||||
|
||||
**Linux/Mac:**
|
||||
```bash
|
||||
./run-coverage.sh
|
||||
```
|
||||
|
||||
### What Happens
|
||||
|
||||
1. Builds test environment
|
||||
2. Runs `mvn test` with JaCoCo agent
|
||||
3. Generates coverage reports (HTML, XML, CSV)
|
||||
4. Exports to `./target/site/jacoco/`
|
||||
|
||||
### Output
|
||||
|
||||
**Console:**
|
||||
```
|
||||
=================================================================================
|
||||
Coverage report generated successfully!
|
||||
=================================================================================
|
||||
HTML Report: ./target/site/jacoco/index.html
|
||||
XML Report: ./target/site/jacoco/jacoco.xml
|
||||
CSV Report: ./target/site/jacoco/jacoco.csv
|
||||
=================================================================================
|
||||
```
|
||||
|
||||
**Files:**
|
||||
- `./target/site/jacoco/index.html` ← **Open this in browser**
|
||||
- `./target/site/jacoco/jacoco.xml` (for CI/CD)
|
||||
- `./target/site/jacoco/jacoco.csv` (for spreadsheets)
|
||||
|
||||
---
|
||||
|
||||
## Complete Workflow
|
||||
|
||||
### Typical Development Cycle
|
||||
|
||||
```bash
|
||||
# 1. Write code
|
||||
vim src/main/java/com/example/service/MyService.java
|
||||
|
||||
# 2. Run tests
|
||||
docker-compose -f docker-compose.test.yml up --build
|
||||
docker-compose -f docker-compose.test.yml down
|
||||
|
||||
# 3. Check coverage
|
||||
docker-compose -f docker-compose.coverage.yml up --build
|
||||
docker-compose -f docker-compose.coverage.yml down
|
||||
|
||||
# 4. View coverage report
|
||||
# Open target/site/jacoco/index.html in browser
|
||||
|
||||
# 5. Deploy if tests pass
|
||||
docker-compose up -d --build
|
||||
|
||||
# 6. Verify
|
||||
curl http://localhost:8080/jaxws-hello-world/hello?wsdl
|
||||
|
||||
# 7. View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# 8. Stop when done
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Using Convenience Scripts (Faster)
|
||||
|
||||
**Windows:**
|
||||
```cmd
|
||||
REM 1. Write code
|
||||
notepad src\main\java\com\example\service\MyService.java
|
||||
|
||||
REM 2. Run tests
|
||||
run-tests.bat
|
||||
|
||||
REM 3. Generate coverage
|
||||
run-coverage.bat
|
||||
|
||||
REM 4. View coverage
|
||||
start target\site\jacoco\index.html
|
||||
|
||||
REM 5. Deploy
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
**Linux/Mac:**
|
||||
```bash
|
||||
# 1. Write code
|
||||
vim src/main/java/com/example/service/MyService.java
|
||||
|
||||
# 2. Run tests
|
||||
./run-tests.sh
|
||||
|
||||
# 3. Generate coverage
|
||||
./run-coverage.sh
|
||||
|
||||
# 4. View coverage (Linux)
|
||||
xdg-open target/site/jacoco/index.html
|
||||
|
||||
# 5. Deploy
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Table
|
||||
|
||||
| Task | Docker Compose Command | Script Alternative |
|
||||
|------|----------------------|-------------------|
|
||||
| **Run Tests** | `docker-compose -f docker-compose.test.yml up --build` | `run-tests.bat` / `./run-tests.sh` |
|
||||
| **Generate Coverage** | `docker-compose -f docker-compose.coverage.yml up --build` | `run-coverage.bat` / `./run-coverage.sh` |
|
||||
| **Start Server** | `docker-compose up -d` | N/A |
|
||||
| **Stop Server** | `docker-compose down` | N/A |
|
||||
| **View Logs** | `docker-compose logs -f` | N/A |
|
||||
| **Rebuild Server** | `docker-compose up -d --build` | N/A |
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern: Test-Driven Development (TDD)
|
||||
|
||||
```bash
|
||||
# Watch-test loop (manual)
|
||||
while true; do
|
||||
docker-compose -f docker-compose.test.yml up --build
|
||||
docker-compose -f docker-compose.test.yml down
|
||||
read -p "Press Enter to run again, Ctrl+C to exit..."
|
||||
done
|
||||
```
|
||||
|
||||
### Pattern: CI/CD Pipeline
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Run Tests
|
||||
run: docker-compose -f docker-compose.test.yml up --build
|
||||
|
||||
- name: Generate Coverage
|
||||
run: docker-compose -f docker-compose.coverage.yml up --build
|
||||
|
||||
- name: Upload Coverage
|
||||
uses: codecov/codecov-action@v3
|
||||
with:
|
||||
files: ./target/site/jacoco/jacoco.xml
|
||||
|
||||
- name: Deploy (if tests pass)
|
||||
run: docker-compose up -d --build
|
||||
```
|
||||
|
||||
### Pattern: Pre-commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Running tests before commit..."
|
||||
docker-compose -f docker-compose.test.yml up --build
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Tests failed! Commit aborted."
|
||||
docker-compose -f docker-compose.test.yml down
|
||||
exit 1
|
||||
fi
|
||||
|
||||
docker-compose -f docker-compose.test.yml down
|
||||
echo "Tests passed! Proceeding with commit."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tests Failing
|
||||
|
||||
```bash
|
||||
# View detailed test output
|
||||
docker-compose -f docker-compose.test.yml up
|
||||
|
||||
# Check test container logs
|
||||
docker-compose -f docker-compose.test.yml logs
|
||||
|
||||
# Access test container
|
||||
docker-compose -f docker-compose.test.yml run --rm test bash
|
||||
```
|
||||
|
||||
### Coverage Report Empty
|
||||
|
||||
```bash
|
||||
# Ensure tests are running
|
||||
docker-compose -f docker-compose.test.yml up --build
|
||||
|
||||
# Check if target directory is mounted
|
||||
docker-compose -f docker-compose.coverage.yml config | grep target
|
||||
|
||||
# Manually verify mount
|
||||
ls -la target/site/jacoco/
|
||||
```
|
||||
|
||||
### Server Won't Start
|
||||
|
||||
```bash
|
||||
# Check if port 8080 is in use
|
||||
netstat -ano | findstr :8080 # Windows
|
||||
lsof -i :8080 # Linux/Mac
|
||||
|
||||
# View server logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Rebuild from scratch
|
||||
docker-compose down
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Run Specific Test
|
||||
|
||||
```bash
|
||||
# Override command to run specific test
|
||||
docker-compose -f docker-compose.test.yml run --rm test \
|
||||
mvn test -Dtest=HelloWorldServiceImplTest
|
||||
```
|
||||
|
||||
### Custom Memory Settings
|
||||
|
||||
```bash
|
||||
# Override environment variable
|
||||
docker-compose -f docker-compose.test.yml run --rm \
|
||||
-e MAVEN_OPTS="-Xmx1024m" test mvn test
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Run tests with Maven debug output
|
||||
docker-compose -f docker-compose.test.yml run --rm test \
|
||||
mvn test -X
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- **3 Docker Compose files** = 3 different purposes
|
||||
- **Test first** before deploying
|
||||
- **Check coverage** to ensure quality
|
||||
- **Use scripts** for convenience
|
||||
- **All outputs** go to `./target/`
|
||||
|
||||
**Quick commands to remember:**
|
||||
```bash
|
||||
run-tests.bat # or ./run-tests.sh
|
||||
run-coverage.bat # or ./run-coverage.sh
|
||||
docker-compose up -d # start server
|
||||
```
|
||||
|
||||
That's it! You now have everything you need to use Docker Compose patterns in this project.
|
||||
Reference in New Issue
Block a user