Backend Setup Guide

Complete guide for setting up the Delivery Tracking App backend with Kafka KRaft (no Zookeeper), Prometheus, and Grafana.

Prerequisites
Step 1: Kafka KRaft Setup
Step 2: Prometheus Setup
Step 3: Grafana Setup
Step 4: Spring Boot Application
API Reference
Troubleshooting

Prerequisites

Java 17 or higher
Maven 3.8+
Windows/Linux/MacOS

Step 1: Kafka KRaft Setup

Kafka KRaft mode eliminates the need for Zookeeper, simplifying the setup.

1.1 Download and Extract Kafka

# Windows PowerShell
$kafkaVersion = "3.6.1"
Invoke-WebRequest -Uri "https://downloads.apache.org/kafka/$kafkaVersion/kafka_2.13-$kafkaVersion.tgz" -OutFile "kafka.tgz"
tar -xzf kafka.tgz
Rename-Item "kafka_2.13-$kafkaVersion" "kafka"

Or download manually from Apache Kafka Downloads

1.2 Generate KRaft Cluster ID

cd kafka
bin\windows\kafka-storage.bat random-uuid

Save the generated UUID (e.g., abc123def456ghi789)

1.3 Format Storage

bin\windows\kafka-storage.bat format -t <YOUR_CLUSTER_ID> -c config\kraft\server.properties

1.4 Configure Kafka

Edit config/kraft/server.properties:

# Listeners
listeners=PLAINTEXT://localhost:9092,CONTROLLER://localhost:9093
advertised.listeners=PLAINTEXT://localhost:9092

# Log directories
log.dirs=C:/kafka/kraft-logs

# Node settings
node.id=1
process.roles=broker,controller
controller.quorum.voters=1@localhost:9093

# Topic settings
auto.create.topics.enable=true
num.partitions=1
default.replication.factor=1
min.insync.replicas=1

1.5 Start Kafka

bin\windows\kafka-server-start.bat config\kraft\server.properties

Verify Kafka is running by checking port 9092.

1.6 Create Required Topic

# In a new terminal
bin\windows\kafka-topics.bat --create --topic delivery-location --bootstrap-server localhost:9092 --partitions 1 --replication-factor 1

# Verify topic creation
bin\windows\kafka-topics.bat --list --bootstrap-server localhost:9092

Step 2: Prometheus Setup

2.1 Download Prometheus

$promVersion = "2.48.0"
Invoke-WebRequest -Uri "https://github.com/prometheus/prometheus/releases/download/v$promVersion/prometheus-$promVersion.windows-amd64.zip" -OutFile "prometheus.zip"
Expand-Archive -Path "prometheus.zip" -DestinationPath "."
Rename-Item "prometheus-$promVersion.windows-amd64" "prometheus"

2.2 Configure Prometheus

Create prometheus.yml in the prometheus folder:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'delivery-app'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['localhost:8080']
    scrape_interval: 5s

  - job_name: 'kafka'
    static_configs:
      - targets: ['localhost:9092']

2.3 Start Prometheus

cd prometheus
.\prometheus.exe --config.file=prometheus.yml

Access Prometheus UI at: http://localhost:9090

Step 3: Grafana Setup

3.1 Download and Extract Grafana

$grafanaVersion = "10.2.3"
Invoke-WebRequest -Uri "https://dl.grafana.com/oss/release/grafana-$grafanaVersion.windows-amd64.zip" -OutFile "grafana.zip"
Expand-Archive -Path "grafana.zip" -DestinationPath "."

3.2 Start Grafana

cd grafana-$grafanaVersion\bin
.\grafana-server.exe

Access Grafana UI at: http://localhost:3000

Default username: admin
Default password: admin

3.3 Configure Grafana

Add Prometheus Data Source:
- Go to Configuration → Data Sources
- Click "Add data source"
- Select "Prometheus"
- URL: http://localhost:9090
- Click "Save & Test"
Import Delivery Dashboard:
- Go to Create → Import
- Use dashboard ID: 1860 (Node Exporter) or create custom
- Or import the JSON below:

{
  "dashboard": {
    "title": "Delivery Tracking Dashboard",
    "panels": [
      {
        "title": "Active Deliveries",
        "type": "stat",
        "targets": [
          {
            "expr": "delivery_in_transit_count"
          }
        ]
      },
      {
        "title": "Delivered Today",
        "type": "stat",
        "targets": [
          {
            "expr": "delivery_delivered_count"
          }
        ]
      },
      {
        "title": "Average Delivery Time",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(delivery_time_seconds_sum[5m]) / rate(delivery_time_seconds_count[5m])"
          }
        ]
      }
    ]
  }
}

Step 4: Spring Boot Application

4.1 Configure Application

Edit src/main/resources/application.properties:

spring:
  application:
    name: delivery-tracking-app
  kafka:
    bootstrap-servers: localhost:9092
    consumer:
      group-id: delivery-group
      auto-offset-reset: earliest
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: org.apache.kafka.common.serialization.StringSerializer

server:
  port: 8080

management:
  endpoints:
    web:
      exposure:
        include: prometheus,health,info,metrics
  endpoint:
    prometheus:
      enabled: true
  metrics:
    export:
      prometheus:
        enabled: true

4.2 Build and Run

# Build
.\mvnw clean package -DskipTests

# Run
.\mvnw spring-boot:run

# Or run the JAR
java -jar target\Backend-1-0.0.1-SNAPSHOT.jar

4.3 Verify Backend

Health Check: http://localhost:8080/actuator/health
Metrics: http://localhost:8080/actuator/prometheus
API Base: http://localhost:8080/api/delivery

API Reference

Location Updates

POST /api/delivery/update
Content-Type: application/json

{
  "orderId": "ORD001",
  "latitude": 18.5074,
  "longitude": 73.8077,
  "status": "in-transit",
  "etaMinutes": 15.5,
  "speedKmh": 25.3,
  "driverName": "John Doe",
  "vehicleId": "VH001"
}

Get Delivery History

GET /api/delivery/history/{orderId}

Get History by Time Range

GET /api/delivery/history/{orderId}/range?from=2024-01-15T10:00:00Z&to=2024-01-15T11:00:00Z

Get Active Deliveries

GET /api/delivery/active

Get Delivery Summary

GET /api/delivery/summary/{orderId}

Get All Summaries

GET /api/delivery/summaries

List All Orders

GET /api/delivery/orders

Clear History

DELETE /api/delivery/history/{orderId}

Metrics Exposed

Metric Name	Type	Description
`delivery_placed_count`	Gauge	Orders in placed state
`delivery_in_transit_count`	Gauge	Orders in transit
`delivery_delivered_count`	Gauge	Delivered orders
`delivery_failed_count`	Gauge	Failed deliveries
`delivery_time_seconds`	Summary	Delivery duration

Troubleshooting

Kafka Issues

Problem: Kafka fails to start with "Address already in use" Solution:

# Find and kill process using port 9092
netstat -ano | findstr :9092
taskkill /PID <PID> /F

Problem: "Failed to load properties from config/kraft/server.properties" Solution: Use absolute paths in log.dirs configuration

Prometheus Issues

Problem: "connection refused" when scraping Solution: Ensure Spring Boot app is running and management.endpoints.web.exposure.include includes prometheus

Spring Boot Issues

Problem: "Connection to node -1 could not be established" Solution: Verify Kafka is running on localhost:9092

Problem: WebSocket connection fails Solution: Check CORS configuration in DeliveryController.java

Useful Commands

Kafka Commands

# List topics
bin\windows\kafka-topics.bat --list --bootstrap-server localhost:9092

# Describe topic
bin\windows\kafka-topics.bat --describe --topic delivery-location --bootstrap-server localhost:9092

# Consume messages
bin\windows\kafka-console-consumer.bat --topic delivery-location --from-beginning --bootstrap-server localhost:9092

# Delete topic
bin\windows\kafka-topics.bat --delete --topic delivery-location --bootstrap-server localhost:9092

Maven Commands

# Clean build
.\mvnw clean package

# Run tests
.\mvnw test

# Run with profile
.\mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Project Structure

Backend/
├── src/main/java/com/example/tracking/
│   ├── config/           # Configuration classes
│   │   ├── JacksonConfig.java
│   │   ├── KafkaConfig.java
│   │   └── WebSocketConfig.java
│   ├── controller/       # REST API controllers
│   │   └── DeliveryController.java
│   ├── metrics/          # Micrometer metrics
│   │   └── DeliveryMetrics.java
│   ├── model/            # Data models
│   │   └── DeliveryLocation.java
│   ├── service/          # Business logic
│   │   ├── DeliveryConsumer.java
│   │   ├── DeliveryHistoryService.java
│   │   ├── DeliveryProducer.java
│   │   ├── DeliverySimulator.java
│   │   ├── EnhancedDeliverySimulator.java
│   │   └── OsrmRouteService.java
│   └── util/             # Utility classes
│       └── PolylineDecoder.java
├── src/main/resources/
│   └── application.properties
├── pom.xml
└── README.md

FilesExpand file tree

README.md

Latest commit

History