initial commit

Change-Id: I9c68c43e939d2c1a3b95a68b71ecc5ba861a4df5

docs/local-development.md

@@ -0,0 +1,279 @@
+# 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)