280 lines
5.0 KiB
Markdown
280 lines
5.0 KiB
Markdown
# 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)
|