online-boutique/README.md

# online-boutique

> Java microservice via Golden Path

## Overview

This service was scaffolded using the **Java Golden Path** template in Backstage. It provides:

- ✅ Production-ready Spring Boot 3.2 application
- ✅ Prometheus metrics integration
- ✅ Health checks and readiness probes
- ✅ Humanitec deployment orchestration
- ✅ GitOps-ready Kubernetes manifests
- ✅ CI/CD via GitHub Actions
- ✅ Grafana dashboard integration

## Quick Start

### Local Development

```bash
# Build and run locally
./mvnw spring-boot:run

# Or with Docker
docker build -t online-boutique:latest .
docker run -p 8080:8080 online-boutique:latest
```

Access the application:
- **Application**: http://localhost:8080
- **Health**: http://localhost:8080/actuator/health
- **Metrics**: http://localhost:8080/actuator/prometheus

### Build

```bash
# Maven build
./mvnw clean package

# Output: target/online-boutique-1.0.0-SNAPSHOT.jar
```

### Test

```bash
./mvnw test
```

## Deployment

### Humanitec (Primary)

Deployments are automatically triggered on push to `main` branch via GitHub Actions:

1. **Build**: Maven builds the JAR
2. **Container**: Docker image built and pushed to ACR
3. **Deploy**: Humanitec CLI deploys using `score.yaml`

View deployment status:
- **Humanitec Console**: https://app.humanitec.io/orgs/kyn-cjot/apps/online-boutique

### ArgoCD (Fallback)

If Humanitec is unavailable, deploy via ArgoCD using manifests in `deploy/`:

```bash
kubectl apply -k deploy/
```

## Monitoring

### Grafana Dashboard

View real-time metrics:
- **URL**: https://grafana.kyndemo.live/d/spring-boot-dashboard?var-app=online-boutique

Metrics include:
- HTTP request rate and latency
- Error rates (4xx, 5xx)
- JVM memory and GC
- CPU usage
- Thread pools

### Prometheus Metrics

Exposed at `/actuator/prometheus`:
- `http_server_requests_seconds` - Request metrics
- `jvm_memory_used_bytes` - Memory usage
- `process_cpu_usage` - CPU utilization

### Health Checks

- **Liveness**: `/actuator/health/liveness`
- **Readiness**: `/actuator/health/readiness`
- **Overall**: `/actuator/health`

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Welcome message |
| `/api/status` | GET | Service status |
| `/actuator/health` | GET | Health check |
| `/actuator/prometheus` | GET | Prometheus metrics |
| `/actuator/info` | GET | Application info |

## Configuration

### Environment Variables

- `SPRING_PROFILES_ACTIVE` - Active profile (dev, staging, production)
- `SERVER_PORT` - HTTP port (default: 8080)

### Profiles

- **development**: Local dev settings
- **production**: Production optimized settings

## Architecture

```
┌─────────────────────────────────────────┐
│         GitHub Actions (CI/CD)          │
│  - Build with Maven                     │
│  - Push to ACR                          │
│  - Deploy via Humanitec                 │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Humanitec Orchestrator          │
│  - Interprets score.yaml                │
│  - Provisions resources                 │
│  - Deploys to AKS                       │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Azure AKS Cluster               │
│  - Running application pods             │
│  - Prometheus scraping metrics          │
│  - Ingress routing traffic              │
└─────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│         Grafana Dashboard               │
│  - Visualizing metrics                  │
│  - Alerting on issues                   │
└─────────────────────────────────────────┘
```

## Development

### Adding New Endpoints

Edit `src/main/java/com/kyndryl/goldenpath/GoldenPathApplication.java`:

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

### Adding Custom Metrics

Inject `MeterRegistry` and create custom metrics:

```java
@RestController
public class MyController {
    private final Counter myCounter;
    
    public MyController(MeterRegistry registry) {
        this.myCounter = Counter.builder("my_custom_counter")
            .tag("service", "online-boutique")
            .register(registry);
    }
    
    @GetMapping("/api/data")
    public String getData() {
        myCounter.increment();
        return "data";
    }
}
```

### Database Integration

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>
    <scope>runtime</scope>
</dependency>
```

Update `score.yaml` to provision PostgreSQL via Humanitec:

```yaml
resources:
  database:
    type: postgres
    properties:
      version: "15"
```

## Troubleshooting

### Build Fails

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

# Check dependencies
./mvnw dependency:tree
```

### Metrics Not Showing

1. Verify endpoint: `curl localhost:8080/actuator/prometheus`
2. Check pod annotations in `deploy/deployment.yaml`
3. Verify Prometheus targets in Grafana

### Deployment Fails

1. Check GitHub Actions logs
2. Review Humanitec deployment logs
3. Check pod status: `kubectl get pods -n demo-apps`

## Links

- **Repository**: https://gitea.kyndemo.live/validate/online-boutique
- **Humanitec**: https://app.humanitec.io/orgs/kyn-cjot/apps/online-boutique
- **Grafana**: https://grafana.kyndemo.live/d/spring-boot-dashboard?var-app=online-boutique
- **Backstage Catalog**: https://backstage.kyndemo.live/catalog/default/component/online-boutique

## Support

For issues or questions:
1. Check documentation in `docs/`
2. Review Backstage TechDocs
3. Contact Platform Engineering team