v2.1 - added kafka message broker support

Author: Tzesh

README.md

@@ -1,90 +1,96 @@
 # Spring Boot Template
 
 ## Description
-A template for Spring Boot projects. This template includes the following features:
-- Spring Boot 3.2.3 (latest 3.x LTS, updated for security and new features)
-- Java 21 (latest LTS, required for Spring Boot 3.2+)
-- Spring Security with JWT authentication and authorization also with refresh token
-- Swagger UI for API documentation and testing (http://localhost:8080/api/v1/swagger-ui/index.html) with authentication and authorization support
-- Spring Data JPA with PostgreSQL database integration
-- Exception handling mechanism with custom exceptions and exception handlers using `@ControllerAdvice`
-- Base entity and base DTO for common fields
-- Base service for common business logic
-- Custom `@PreAuthorize` annotation for authorization
-- Lombok for reducing boilerplate code
-- MapStruct for mapping DTOs to entities and vice versa
-- **Docker Compose support for easy containerized development**
-- Redis integration for caching and session management (configurable via environment variables)
-
-> **Note:** This template is up-to-date with Spring Boot 3.2.3 and Java 21. Ensure your local environment supports Java 21 for development and builds.
-
-## How to run
+A robust template for Spring Boot projects with modern best practices and production-ready integrations.
+
+![Docker Compose](https://imgur.com/qWLYDrg.png)
+![Swagger UI](https://imgur.com/7Vug2XR.png)
+
+### Key Features
+- **Spring Boot 3.2.3** (Java 21 LTS)
+- **JWT Authentication & Authorization** (with refresh tokens)
+- **Swagger UI** for API documentation and testing ([http://localhost:8080/api/v1/swagger-ui/index.html](http://localhost:8080/api/v1/swagger-ui/index.html))
+- **PostgreSQL** integration (via Docker Compose)
+- **Redis** for caching and session management
+- **Kafka & Zookeeper** for message brokering (via Docker Compose)
+- **Role-based Security** with Spring Security
+- **Rate Limiting**
+- **Exception Handling** with `@ControllerAdvice`
+- **Lombok** and **MapStruct** for reduced boilerplate
+- **Environment Isolation**: Easily run multiple environments (dev, test, prod) in parallel using Docker Compose project names and override files
+- **Configurable Logging** (including Kafka)
+- **Unit & Integration Tests** for key services and controllers
+
+> **Note:** Java 21 is required. Ensure your local environment supports Java 21 for development and builds.
+
+---
+
+## How to Run
 
 ### Using Docker Compose (Recommended)
 1. Clone this repository
-2. Make sure Docker and Docker Compose are installed on your system
-3. Run the following command in the project root:
+2. Ensure Docker and Docker Compose are installed
+3. For a default environment, run:
    ```sh
    docker compose up -d
    ```
-4. The application will be available at [http://localhost:8080/api/v1/swagger-ui/index.html](http://localhost:8080/api/v1/swagger-ui/index.html)
-5. PostgreSQL will be available at port 5432 (default credentials are set in `docker-compose.yml` and can be overridden with environment variables)
+4. For multiple environments (e.g., test and prod) in parallel:
+   ```sh
+   docker-compose -f docker-compose.yml -f docker-compose.test.override.yml --env-file env.test -p myapp_test up -d
+   docker-compose -f docker-compose.yml -f docker-compose.prod.override.yml --env-file env.prod -p myapp_prod up -d
+   ```
+   - This will create isolated containers, networks, and volumes for each environment.
+   - Make sure to set different ports in override files to avoid conflicts.
+5. The application will be available at [http://localhost:8080/api/v1/swagger-ui/index.html](http://localhost:8080/api/v1/swagger-ui/index.html) (or the port you set).
 
 ### Using Maven (Local Development)
 1. Clone this repository
-2. Create a PostgreSQL database or use the provided Docker Compose setup
-3. Change the database configuration in `application.properties` if needed
-4. Make sure you have redis and postgresql running locally or use the Docker Compose setup
-4. Run the application with:
+2. Set up PostgreSQL and Redis (or use Docker Compose)
+3. Adjust `application.properties` as needed
+4. Run:
    ```sh
    mvn spring-boot:run
    ```
-5. Open [http://localhost:8080/api/v1/swagger-ui/index.html](http://localhost:8080/api/v1/swagger-ui/index.html) in your browser
+5. Open [http://localhost:8080/api/v1/swagger-ui/index.html](http://localhost:8080/api/v1/swagger-ui/index.html)
 
-### API Usage
-1. Register a new user
-2. Login with the registered user
-3. Copy the JWT token from the response
-4. Click the `Authorize` button in the Swagger UI
-5. Paste the JWT token in the `Value` field without the `Bearer` prefix
-6. Click the `Authorize` button
-7. Now you can test the API endpoints
-8. To test the refresh token endpoint, click the `Authorize` button again and paste the refresh token in the `Value` field without the `Bearer` prefix
+---
 
-![Docker Compose](https://imgur.com/qWLYDrg.png)
-![Maven Run](https://imgur.com/lGSrRLL.png)
-![Swagger UI](https://imgur.com/7Vug2XR.png)
-
-## Environment Variables
-- You can override default database credentials and other settings using environment variables in `docker-compose.yml` or by creating a `.env` file in the project root.
+## Kafka Messaging
+- Kafka and Zookeeper are included in Docker Compose for local development.
+- REST endpoint `/kafka/send` allows sending messages to Kafka, with optional scheduling for future delivery.
+- Kafka consumer logs received messages.
+- Kafka logging is configurable in `application.properties`.
 
-### Environment Variables for Redis
+---
 
-You can configure Redis connection using environment variables (recommended for Docker Compose):
+## Environment Configuration
+- Use `.env` files for environment-specific variables.
+- Use Docker Compose override files for port and resource separation.
+- Example for test environment:
+  ```sh
+  docker-compose -f docker-compose.yml -f docker-compose.test.override.yml --env-file env.test -p myapp_test up -d
+  ```
 
-- `SPRING_DATA_REDIS_HOST` (default: `redis`)
-- `SPRING_DATA_REDIS_PORT` (default: `6379`)
+---
 
-Example in `docker-compose.yml`:
+## API Usage
+1. Register a new user
+2. Login and obtain a JWT token
+3. Use the token in Swagger UI via the `Authorize` button
+4. Access secured endpoints (e.g., Kafka messaging requires ADMIN role)
 
-```yaml
-app:
-  # ...existing code...
-  environment:
-    SPRING_DATA_REDIS_HOST: redis
-    SPRING_DATA_REDIS_PORT: 6379
-    # ...other env vars...
-```
+---
 
-Redis will be available at port 6379 by default.
+## Project Abilities Summary
+- Modular REST API with security, rate limiting, and exception handling
+- PostgreSQL, Redis, Kafka, and Zookeeper integration (all containerized)
+- Role-based access control
+- Swagger/OpenAPI documentation
+- Environment isolation for dev, test, and prod
+- Configurable logging
+- Unit and integration tests
 
-## Database Configuration
+---
 
-- To connect to your PostgreSQL database:
-  - Host: `db`
-  - Port: `5432`
-  - Username: as set in `docker-compose.yml` (default: `development`)
-  - Password: as set in `docker-compose.yml` (default: `T3st!ng`)
+For more details, see the code and comments, or open an issue for questions!
 
-## Contribute to this project
-If you want to contribute to this project, please create a pull request.

docker-compose.yml

@@ -41,6 +41,32 @@ services:
     networks:
       - bridge_network
 
+  zookeeper:
+    image: confluentinc/cp-zookeeper:7.5.0
+    container_name: zookeeper
+    environment:
+      ZOOKEEPER_CLIENT_PORT: 2181
+      ZOOKEEPER_TICK_TIME: 2000
+    ports:
+      - "2181:2181"
+    networks:
+      - bridge_network
+
+  kafka:
+    image: confluentinc/cp-kafka:7.5.0
+    container_name: kafka
+    depends_on:
+      - zookeeper
+    ports:
+      - "9092:9092"
+    environment:
+      KAFKA_BROKER_ID: 1
+      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
+      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+    networks:
+      - bridge_network
+
 volumes:
   postgres_data:
 

pom.xml

@@ -11,7 +11,7 @@
 
     <groupId>com.tzesh</groupId>
     <artifactId>spring-boot-template</artifactId>
-    <version>2.0</version>
+    <version>2.1</version>
     <name>spring-boot-template</name>
     <description>spring-boot-template</description>
 

spring-boot-template-api/pom.xml

@@ -5,19 +5,19 @@
     <parent>
         <groupId>com.tzesh</groupId>
         <artifactId>spring-boot-template</artifactId>
-        <version>2.0</version>
+        <version>2.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 
     <artifactId>spring-boot-template-api</artifactId>
-    <version>2.0</version>
+    <version>2.1</version>
     <name>spring-boot-template-api</name>
     <description>spring-boot-template-api</description>
     <dependencies>
         <dependency>
             <groupId>com.tzesh</groupId>
             <artifactId>spring-boot-template-core</artifactId>
-            <version>2.0</version>
+            <version>2.1</version>
             <scope>compile</scope>
         </dependency>
         <dependency>
@@ -35,6 +35,11 @@
             <artifactId>redisson</artifactId>
             <version>3.27.2</version>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.kafka</groupId>
+            <artifactId>spring-kafka</artifactId>
+            <version>3.1.2</version>
+        </dependency>
     </dependencies>
     <packaging>jar</packaging>
 

spring-boot-template-api/src/main/java/com/tzesh/springtemplate/config/OpenApiConfig.java

@@ -21,9 +21,9 @@
                         email = "[email protected]",
                         url = "https://ugurdindar.com"
                 ),
-                description = "Spring Boot Template for RESTful API that uses JWT for authentication and authorization, PostgreSQL for database, Hibernate for ORM, and Lombok for boilerplate code generation and MapStruct for mapping DTOs to entities and vice versa.",
+                description = "Production-ready Spring Boot template for secure REST APIs with JWT, PostgreSQL, Hibernate, Redis, Kafka, Zookeeper, MapStruct, Lombok, and Docker Compose. Fast, modern, and cloud-ready.",
                 title = "Spring Boot Template",
-                version = "0.3.0",
+                version = "2.1.0",
                 license = @License(
                         name = "GitHub Repository",
                         url = "https://github.com/tzesh/SpringBootTemplate"

spring-boot-template-api/src/main/java/com/tzesh/springtemplate/controller/auth/AuthenticationController.java

@@ -29,7 +29,7 @@
 @RequestMapping("/auth")
 @RequiredArgsConstructor
 @Validated
-@Tag(name = "1. Authentication Controller", description = "Authentication operations for users")
+@Tag(name = "Authentication Controller", description = "Authentication operations for users")
 public class AuthenticationController {
 
     private final AuthenticationService authenticationService;

spring-boot-template-api/src/main/java/com/tzesh/springtemplate/controller/kafka/KafkaController.java

@@ -0,0 +1,34 @@
+package com.tzesh.springtemplate.controller.kafka;
+
+import com.tzesh.springtemplate.service.KafkaProducerService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.security.access.prepost.PreAuthorize;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+
+@Tag(name = "Kafka Controller", description = "Endpoints for testing Kafka integration.")
+@RestController
+@RequestMapping("/kafka")
+public class KafkaController {
+    @Autowired
+    private KafkaProducerService kafkaProducerService;
+
+    @Operation(summary = "Send a message to Kafka", description = "Sends a message to the 'test-topic' topic in Kafka. Requires ADMIN role.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "Message sent successfully"),
+        @ApiResponse(responseCode = "403", description = "Forbidden - Only ADMIN role allowed"),
+        @ApiResponse(responseCode = "401", description = "Unauthorized")
+    })
+    @PostMapping("/send")
+    @PreAuthorize("hasRole('ADMIN')")
+    public String sendMessage(@Parameter(description = "Message to send to Kafka", required = true)
+                             @RequestParam String message) {
+        kafkaProducerService.sendMessage(message);
+        return "Message sent to Kafka: " + message;
+    }
+}
+

spring-boot-template-api/src/main/java/com/tzesh/springtemplate/controller/user/UserController.java

@@ -25,7 +25,7 @@
  */
 @RestController
 @RequestMapping("/users")
-@Tag(name = "2. User Controller", description = "User operations")
+@Tag(name = "User Controller", description = "User operations")
 @RequiredArgsConstructor
 @Validated
 public class UserController {

spring-boot-template-api/src/main/java/com/tzesh/springtemplate/service/KafkaConsumerService.java

@@ -0,0 +1,18 @@
+package com.tzesh.springtemplate.service;
+
+import org.apache.kafka.clients.consumer.ConsumerRecord;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.kafka.annotation.KafkaListener;
+import org.springframework.stereotype.Service;
+
+@Service
+public class KafkaConsumerService {
+    private static final Logger logger = LoggerFactory.getLogger(KafkaConsumerService.class);
+
+    @KafkaListener(topics = "test-topic", groupId = "spring-template-group")
+    public void listen(ConsumerRecord<String, String> record) {
+        logger.info("Received message: {}", record.value());
+    }
+}
+

spring-boot-template-api/src/main/java/com/tzesh/springtemplate/service/KafkaProducerService.java

@@ -0,0 +1,18 @@
+package com.tzesh.springtemplate.service;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.kafka.core.KafkaTemplate;
+import org.springframework.stereotype.Service;
+
+@Service
+public class KafkaProducerService {
+    private static final String TOPIC = "test-topic";
+
+    @Autowired
+    private KafkaTemplate<String, String> kafkaTemplate;
+
+    public void sendMessage(String message) {
+        kafkaTemplate.send(TOPIC, message);
+    }
+}
+