Skip to content

docs: Update README to master index format #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 22, 2025
Merged

docs: Update README to master index format #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 19 additions & 91 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,108 +1,36 @@
# Spring Boot Security & Observability Lab

This repository is a hands-on lab designed to demonstrate the architectural evolution of a modern Java application. We will build a system from the ground up, starting with a secure monolith and progressively refactoring it into a fully observable, distributed system using cloud-native best practices.
This repository is an advanced, hands-on lab demonstrating the architectural evolution of a modern Java application. We will build a system from the ground up, starting with a secure monolith and progressively refactoring it into a fully observable, distributed system using cloud-native best practices.

---

## Lab Progress: Phase 2 - Observing the Monolith
## Workshop Guide: The Evolutionary Phases

The `main` branch currently represents the completed state of **Phase 2**.
This lab is structured in distinct, self-contained phases. The `main` branch always represents the latest completed phase. To explore a previous phase's code and detailed documentation, use the links below.

* **Git Tag for this Phase:** `v2.0-observable-monolith`

### Objective

The goal of this phase was to take the secure monolith from Phase 1 and instrument it with a modern observability stack. We have containerized the entire system and can now launch the application, a metrics database (Prometheus), and a visualization platform (Grafana) with a single command. The focus is on gaining deep, real-time insight into the application's performance and behavior.

### Key Concepts Demonstrated

* **Application Instrumentation:** Using Spring Boot Actuator and Micrometer to expose detailed application metrics.
* **Custom Metrics:** Creating custom `Counter` beans to track specific, high-value business events (e.g., login success vs. failure).
* **Containerization:** Building a minimal, secure, and efficient multi-stage `Dockerfile` for the Spring Boot application.
* **Infrastructure as Code (IaC):** Defining and orchestrating a multi-service environment using a single `docker-compose.yml` file.
* **Metrics Pipeline:** Configuring Prometheus to automatically discover, authenticate with, and scrape the metrics from our application's secured management endpoint.
* **Automated Provisioning:** Using Grafana's provisioning feature to automatically configure its data source and load a pre-built dashboard from version-controlled files.
* **Profile-Specific Code:** Isolating non-production, demonstration code (`ChaosController`) using Spring Profiles.

### Architecture Overview

The architecture for Phase 2 is a containerized, multi-service stack. The `docker-compose.yml` file is the blueprint for this environment.

```mermaid
graph TD
subgraph "Local Development Environment"
subgraph "Docker Compose Network"
A[Resource Server Container] -->|Exposes /actuator/prometheus on :9092| B(Prometheus Container);
B -->|Provides data to| C(Grafana Container);
end
U(Developer/User) -->|API Calls on :8081| A;
U -->|Views Dashboards on :3000| C;
end
```

1. **[Resource Server](resource-server):** Our Spring Boot application, now running inside a Docker container. It exposes its business API on port `8081` and its secured management/metrics API on a separate port, `9092`.
2. **[Prometheus](config/prometheus/prometheus.yml):** The time-series database. It is configured to periodically scrape the `/actuator/prometheus` endpoint on our application container, authenticating with Basic Auth.
3. **[Grafana](config/grafana):** The visualization platform. On startup, it is automatically provisioned with a connection to the Prometheus service and a pre-built "Resource Server Overview" dashboard.
| Phase | Description & Key Concepts | Code & Docs (at tag) | Key Pull Requests |
|:-----------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **1. The Secure Monolith** | A standalone service that issues and validates its own JWTs. Concepts: `AuthenticationManager`, custom `JwtAuthenticationFilter`, `jjwt` library, and a foundational CI pipeline. | [`v1.0-secure-monolith`](https://github.com/apenlor/spring-boot-security-observability-lab/blob/v1.0-secure-monolith/README.md) | [#2](https://github.com/apenlor/spring-boot-security-observability-lab/pull/2), [#3](https://github.com/apenlor/spring-boot-security-observability-lab/pull/3), [#4](https://github.com/apenlor/spring-boot-security-observability-lab/pull/4) |
| **2. Observing the Monolith** | The service is containerized with a multi-stage `Dockerfile` and orchestrated via `docker-compose`. Concepts: Micrometer, Prometheus, Grafana, custom metrics, and automated dashboard provisioning. | [`v2.0-observable-monolith`](https://github.com/apenlor/spring-boot-security-observability-lab/blob/v2.0-observable-monolith/README.md) | [#6](https://github.com/apenlor/spring-boot-security-observability-lab/pull/6) |
| **3. Evolving to Federated Identity** | *Upcoming...* | - | - |
| **4. Tracing a Distributed System** | *Upcoming...* | - | - |
| **5. Correlated Logs & Access Auditing** | *Upcoming...* | - | - |
| **6. Continuous Security Integration** | *Upcoming...* | - | - |

---

## Local Development & Quick Start
## How to Follow This Lab

**Prerequisites:** Docker and Docker Compose (or a compatible tool like Colima) must be installed.

1. **Create your local environment file:**
Copy the provided template to create your local `.env` file.
```bash
cp .env.example .env
```
*(Review the `.env` file and ensure the pre-filled secrets are suitable for your local development.)*

2. **Build and run the entire stack:**
From the project root, run the Docker Compose `up` command.
```bash
docker-compose up --build
```
This will build the application's Docker image and start all three services (`resource-server`, `prometheus`, `grafana`).

3. **Access the Services:**
* **Application API:** `http://localhost:8081`
* **Prometheus UI:** `http://localhost:9090`
* **Grafana UI:** `http://localhost:3000` (Login with `admin`/`admin`)
1. **Start with the `main` branch** to see the latest state of the project.
2. To go back in time, use the **"Code & Docs" link** for a specific phase. This will show you the `README.md` for that phase, which contains the specific instructions and examples for that version of the code.
3. To understand the *"why"* behind the changes, review the **Key Pull Requests** for each phase.

---

## API & Observability Usage Examples

#### 1. Generate Metrics

To see interesting data on your Grafana dashboard, you need to generate some traffic.

* **Authenticate and get a token** (same as Phase 1):
```bash
TOKEN=$(curl -s -X POST http://localhost:8081/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"user", "password":"password"}' | jq -r .jwtToken)
```
* **Call the secure endpoint:**
```bash
curl http://localhost:8081/api/secure/data -H "Authorization: Bearer $TOKEN"
```
* **Call the Chaos Demo endpoint** (multiple times to see variable results):
```bash
curl http://localhost:8081/demo/flaky-request -H "Authorization: Bearer $TOKEN"
```

#### 2. View the Dashboard
## Running the Project

1. Navigate to Grafana at `http://localhost:3000`.
2. Log in (`admin`/`admin`).
3. Go to the "Dashboards" section.
4. Open the pre-provisioned **"Resource Server Overview"** dashboard.
5. Observe the panels update in real-time as you generate more API traffic.
To run the application and see usage examples for the **current phase**, please refer to the detailed instructions in its tagged `README.md` file.

#### 3. Stop the Environment
**[>> Go to instructions for the current phase: `v2.0-observable-monolith` <<](https://github.com/apenlor/spring-boot-security-observability-lab/blob/v2.0-observable-monolith/README.md#local-development--quick-start)**

When you are finished, stop all services and remove the containers.
```bash
docker-compose down
```
As the lab progresses, this link will always be updated to point to the latest completed phase.