Skip to content

Commit 16d33fe

Browse files
apenlorapenlor
authored
docs(readme): update master index for Phase 2 completion (#7)
1 parent 5f05555 commit 16d33fe

File tree

1 file changed

+19
-91
lines changed

1 file changed

+19
-91
lines changed

‎README.md‎

Lines changed: 19 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,36 @@
11
# Spring Boot Security & Observability Lab
22

3-
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.
3+
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.
44

55
---
66

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

9-
The `main` branch currently represents the completed state of **Phase 2**.
9+
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.
1010

11-
* **Git Tag for this Phase:** `v2.0-observable-monolith`
12-
13-
### Objective
14-
15-
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.
16-
17-
### Key Concepts Demonstrated
18-
19-
* **Application Instrumentation:** Using Spring Boot Actuator and Micrometer to expose detailed application metrics.
20-
* **Custom Metrics:** Creating custom `Counter` beans to track specific, high-value business events (e.g., login success vs. failure).
21-
* **Containerization:** Building a minimal, secure, and efficient multi-stage `Dockerfile` for the Spring Boot application.
22-
* **Infrastructure as Code (IaC):** Defining and orchestrating a multi-service environment using a single `docker-compose.yml` file.
23-
* **Metrics Pipeline:** Configuring Prometheus to automatically discover, authenticate with, and scrape the metrics from our application's secured management endpoint.
24-
* **Automated Provisioning:** Using Grafana's provisioning feature to automatically configure its data source and load a pre-built dashboard from version-controlled files.
25-
* **Profile-Specific Code:** Isolating non-production, demonstration code (`ChaosController`) using Spring Profiles.
26-
27-
### Architecture Overview
28-
29-
The architecture for Phase 2 is a containerized, multi-service stack. The `docker-compose.yml` file is the blueprint for this environment.
30-
31-
```mermaid
32-
graph TD
33-
subgraph "Local Development Environment"
34-
subgraph "Docker Compose Network"
35-
A[Resource Server Container] -->|Exposes /actuator/prometheus on :9092| B(Prometheus Container);
36-
B -->|Provides data to| C(Grafana Container);
37-
end
38-
U(Developer/User) -->|API Calls on :8081| A;
39-
U -->|Views Dashboards on :3000| C;
40-
end
41-
```
42-
43-
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`.
44-
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.
45-
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.
11+
| Phase | Description & Key Concepts | Code & Docs (at tag) | Key Pull Requests |
12+
|:-----------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
13+
| **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) |
14+
| **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) |
15+
| **3. Evolving to Federated Identity** | *Upcoming...* | - | - |
16+
| **4. Tracing a Distributed System** | *Upcoming...* | - | - |
17+
| **5. Correlated Logs & Access Auditing** | *Upcoming...* | - | - |
18+
| **6. Continuous Security Integration** | *Upcoming...* | - | - |
4619

4720
---
4821

49-
## Local Development & Quick Start
22+
## How to Follow This Lab
5023

51-
**Prerequisites:** Docker and Docker Compose (or a compatible tool like Colima) must be installed.
52-
53-
1. **Create your local environment file:**
54-
Copy the provided template to create your local `.env` file.
55-
```bash
56-
cp .env.example .env
57-
```
58-
*(Review the `.env` file and ensure the pre-filled secrets are suitable for your local development.)*
59-
60-
2. **Build and run the entire stack:**
61-
From the project root, run the Docker Compose `up` command.
62-
```bash
63-
docker-compose up --build
64-
```
65-
This will build the application's Docker image and start all three services (`resource-server`, `prometheus`, `grafana`).
66-
67-
3. **Access the Services:**
68-
* **Application API:** `http://localhost:8081`
69-
* **Prometheus UI:** `http://localhost:9090`
70-
* **Grafana UI:** `http://localhost:3000` (Login with `admin`/`admin`)
24+
1. **Start with the `main` branch** to see the latest state of the project.
25+
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.
26+
3. To understand the *"why"* behind the changes, review the **Key Pull Requests** for each phase.
7127

7228
---
7329

74-
## API & Observability Usage Examples
75-
76-
#### 1. Generate Metrics
77-
78-
To see interesting data on your Grafana dashboard, you need to generate some traffic.
79-
80-
* **Authenticate and get a token** (same as Phase 1):
81-
```bash
82-
TOKEN=$(curl -s -X POST http://localhost:8081/auth/login \
83-
-H "Content-Type: application/json" \
84-
-d '{"username":"user", "password":"password"}' | jq -r .jwtToken)
85-
```
86-
* **Call the secure endpoint:**
87-
```bash
88-
curl http://localhost:8081/api/secure/data -H "Authorization: Bearer $TOKEN"
89-
```
90-
* **Call the Chaos Demo endpoint** (multiple times to see variable results):
91-
```bash
92-
curl http://localhost:8081/demo/flaky-request -H "Authorization: Bearer $TOKEN"
93-
```
94-
95-
#### 2. View the Dashboard
30+
## Running the Project
9631

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

103-
#### 3. Stop the Environment
34+
**[>> 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)**
10435

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

0 commit comments

Comments
 (0)