# Local Development

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

## Prerequisites

- **Java 17** or higher ([Download](https://adoptium.net/))
- **Maven 3.9+** (included via Maven Wrapper)
- **Docker** (optional, for container testing)
- **Git**

## Quick Start

### 1. Clone the Repository

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

### 2. Build the Application

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

# Or with system Maven
mvn clean package
```

### 3. Run the Application

```bash
# 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

```bash
# 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`:

```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

```bash
# 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:

```bash
# 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

```bash
docker build -t online-boutique:dev .
```

### Run in Docker

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

### Docker Compose (if needed)

Create `docker-compose.yml`:

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

Run with:
```bash
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`:

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

### Remote Debugging

Start with debug enabled:

```bash
./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

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

### Adding Custom Metrics

```java
@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`:
```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`:
```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: user
    password: pass
  jpa:
    hibernate:
      ddl-auto: update
```

## Troubleshooting

### Port 8080 Already in Use

```bash
# 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

```bash
# Clean and rebuild
./mvnw clean install -U

# Skip tests temporarily
./mvnw clean package -DskipTests
```

### Tests Fail

```bash
# Run with verbose output
./mvnw test -X

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

## Next Steps

- [Learn about deployment](deployment.md)
- [Configure monitoring](monitoring.md)
- [Review architecture](architecture.md)