online-boutique/docs/local-development.md

Local Development

This guide covers setting up and running online-boutique on your local machine.

Prerequisites

• Java 17 or higher (Download)
• Maven 3.9+ (included via Maven Wrapper)
• Docker (optional, for container testing)
• Git

Quick Start

1. Clone the Repository

git clone https://gitea.kyndemo.live/validate/online-boutique.git
cd online-boutique

2. Build the Application

# Using Maven Wrapper (recommended)
./mvnw clean package

# Or with system Maven
mvn clean package

3. Run the Application

# Run with Spring Boot Maven plugin
./mvnw spring-boot:run

# Or run the JAR directly
java -jar target/online-boutique-1.0.0-SNAPSHOT.jar

The application will start on http://localhost:8080

4. Verify It's Running

# Check health
curl http://localhost:8080/actuator/health

# Check status
curl http://localhost:8080/api/status

# View metrics
curl http://localhost:8080/actuator/prometheus

Development Workflow

Hot Reload with Spring DevTools

For automatic restarts during development, add Spring DevTools to pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

Changes to Java files will trigger automatic restarts.

Running Tests

# Run all tests
./mvnw test

# Run specific test class
./mvnw test -Dtest=GoldenPathApplicationTests

# Run tests with coverage
./mvnw test jacoco:report

Active Profile

Set active profile via environment variable:

# Development profile
export SPRING_PROFILES_ACTIVE=development
./mvnw spring-boot:run

# Or inline
SPRING_PROFILES_ACTIVE=development ./mvnw spring-boot:run

Docker Development

Build Image Locally

docker build -t online-boutique:dev .

Run in Docker

docker run -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=development \
  online-boutique:dev

Docker Compose (if needed)

Create docker-compose.yml:

version: '3.8'
services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=development

Run with:

docker-compose up

IDE Setup

IntelliJ IDEA

1. Import Project: File → New → Project from Existing Sources
2. Select Maven: Choose Maven as build tool
3. SDK: Configure Java 17 SDK
4. Run Configuration:
   • Main class: com.kyndryl.goldenpath.GoldenPathApplication
   • VM options: -Dspring.profiles.active=development

VS Code

1. Install Extensions:

   • Extension Pack for Java
   • Spring Boot Extension Pack

2. Open Folder: Open the project root

3. Run/Debug: Use Spring Boot Dashboard or F5

Eclipse

1. Import: File → Import → Maven → Existing Maven Projects
2. Update Project: Right-click → Maven → Update Project
3. Run: Right-click on Application class → Run As → Java Application

Debugging

Enable Debug Logging

In application-development.yml:

logging:
  level:
    root: DEBUG
    com.kyndryl.goldenpath: TRACE

Remote Debugging

Start with debug enabled:

./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

Connect debugger to localhost:5005

Common Development Tasks

Adding a New Endpoint

@GetMapping("/api/hello")
public ResponseEntity<String> hello() {
    return ResponseEntity.ok("Hello, World!");
}

Adding Custom Metrics

@Autowired
private MeterRegistry meterRegistry;

@GetMapping("/api/data")
public String getData() {
    Counter counter = Counter.builder("custom_api_calls")
        .tag("endpoint", "data")
        .register(meterRegistry);
    counter.increment();
    return "data";
}

Database Integration (Future)

To add PostgreSQL:

1. Add dependency in pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
</dependency>

2. Configure in application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: user
    password: pass
  jpa:
    hibernate:
      ddl-auto: update

Troubleshooting

Port 8080 Already in Use

# Find process using port 8080
lsof -i :8080

# Kill process
kill -9 <PID>

# Or use different port
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081

Maven Build Fails

# Clean and rebuild
./mvnw clean install -U

# Skip tests temporarily
./mvnw clean package -DskipTests

Tests Fail

# Run with verbose output
./mvnw test -X

# Run single test
./mvnw test -Dtest=GoldenPathApplicationTests#contextLoads

Next Steps

• Learn about deployment
• Configure monitoring
• Review architecture