A modular, production-style microservices reference project for managing courses and reviews with strong focus on:

• API gateway routing
• OAuth2/OIDC security with Keycloak
• Observability (metrics, logs, traces)
• Docker Compose and Kubernetes/Tilt local deployment workflows

• Overview
• Architecture
• Tech Stack
• Prerequisites
• Quick Start (Docker Compose)
• Run with Kubernetes + Tilt
• Core Endpoints
• Keycloak
• Observability
• Troubleshooting

The system is split into domain services and platform components:

• Gateway Service: entry point and request routing
• Course Service: manages course data in PostgreSQL
• Review Service: manages review data in MongoDB
• Course Composite Service: aggregates course + review responses
• Keycloak: identity provider for authn/authz
• Observability stack: Prometheus, Grafana, Loki, Tempo, Fluent Bit, OpenTelemetry Collector

• Java 17, Spring Boot, Spring Cloud Gateway
• PostgreSQL (Course Service)
• MongoDB (Review Service)
• Keycloak (OAuth2/OIDC)
• OpenTelemetry, Prometheus, Grafana, Loki, Tempo, Fluent Bit
• Docker Compose and Kubernetes (Minikube + Tilt)

Install the following before running:

• Java 17+
• Maven 3.8+
• Docker + Docker Compose
• (Optional) Minikube + Tilt for Kubernetes mode
• curl or HTTPie for API validation

Make sure Docker Engine is running.

cd docker
docker compose -f docker-compose-infra.yml up --build

cd docker
docker compose -f docker-compose-observability.yml up --build

From repository root:

sh run.sh docker

or

sh run.sh

minikube start \
  --profile=microservice-deployment \
  --memory=4g \
  --cpus=4 \
  --disk-size=30g \
  --kubernetes-version=v1.31.0 \
  --driver=docker

minikube addons enable ingress --profile microservice-deployment

eval $(minikube -p microservice-deployment docker-env)

sh build-images.sh

tilt up

Optional check:

tilt get uiresources

Each service exposes actuator metrics and Prometheus output.

Ports and hostnames depend on your local setup (Docker vs Kubernetes ingress).

Typical routes exposed through the gateway:

• GET /course
• POST /course
• GET /review
• POST /review
• GET /course-composite/{courseId}

Actuator/metrics examples:

• GET /actuator/health
• GET /actuator/prometheus

Keycloak is used as the identity provider for user authentication and token issuance.

Typical local flow:

1. Open Keycloak admin/UI.
2. Ensure realm, clients, and users are configured.
3. Get a bearer token from Keycloak.
4. Call gateway APIs with Authorization: Bearer <token>.

The token must contain both:

• Check service targets are UP.
• Scrape metrics from /actuator/prometheus.

• Use dashboards for metrics/logs/traces correlation.

• Fluent Bit forwards service logs to Loki.

• Services export traces through OTel collector to Tempo.

• Services fail to start: verify dependent containers (PostgreSQL, MongoDB, Keycloak) are healthy.
• Auth issues (401/403): check token expiration, client config, and realm roles in Keycloak.
• No logs/traces/metrics: ensure Fluent Bit, OTel collector, Prometheus, Loki, and Tempo are running.
• Kubernetes image pull issues: confirm you built images in Minikube Docker context (docker-env).

• This README focuses on readable setup and operational flow.
• Architecture diagrams remain in notes/images.