{"id":18717727,"url":"https://github.com/haphong463/springboot-kafka-microservices","last_synced_at":"2025-08-21T19:09:53.579Z","repository":{"id":255940674,"uuid":"850060255","full_name":"haphong463/springboot-kafka-microservices","owner":"haphong463","description":"Front end: https://github.com/haphong463/ecommerce-frontend","archived":false,"fork":false,"pushed_at":"2024-10-16T09:06:37.000Z","size":77213,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-14T07:44:40.616Z","etag":null,"topics":["docker","event-driven-architecture","java-web","kafka","microservices-architecture","mysql","redis-cache","restful-api","spring-boot-framework"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haphong463.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-30T19:49:46.000Z","updated_at":"2025-06-02T00:09:09.000Z","dependencies_parsed_at":"2025-04-10T04:07:28.207Z","dependency_job_id":"930afb26-de9e-437c-9d56-02c5a1e7c682","html_url":"https://github.com/haphong463/springboot-kafka-microservices","commit_stats":null,"previous_names":["haphong463/springboot-kafka-microservices"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/haphong463/springboot-kafka-microservices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haphong463%2Fspringboot-kafka-microservices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haphong463%2Fspringboot-kafka-microservices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haphong463%2Fspringboot-kafka-microservices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haphong463%2Fspringboot-kafka-microservices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haphong463","download_url":"https://codeload.github.com/haphong463/springboot-kafka-microservices/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haphong463%2Fspringboot-kafka-microservices/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266963331,"owners_count":24013031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","event-driven-architecture","java-web","kafka","microservices-architecture","mysql","redis-cache","restful-api","spring-boot-framework"],"created_at":"2024-11-07T13:17:30.103Z","updated_at":"2025-07-25T06:08:02.007Z","avatar_url":"https://github.com/haphong463.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# E-commerce Backend Microservices Project (Dockerized) 🚀\n\n## Introduction 🌟\n\nWelcome to the **E-commerce Backend Microservices Project**! This project utilizes a microservices architecture to provide a flexible and maintainable e-commerce platform. By using Docker and Docker Compose, developers can easily set up and manage the entire backend ecosystem, including services such as API Gateway, Service Registry (Eureka Server), Product, Order, Email, Identity, and Payment. Modern technologies like Kafka for messaging, OpenFeign for inter-service communication, Redis for temporary data storage, Zipkin for tracing, and MySQL for data storage create a powerful and efficient system.\n\n## Microservices Architecture 🛠️\n\nThe project is divided into several interconnected microservices, each handling specific business functions. Below is an overview of each service:\n\n### 1. API Gateway 🌐\n\n- **Description**: The single entry point for all client requests, routing them to the appropriate microservices.\n- **Technology**: Spring Cloud Gateway\n- **Features**: Security handling, routing, load balancing, and rate limiting.\n\n### 2. Service Registry 📜\n\n- **Description**: Supports dynamic discovery and registration of microservices within the ecosystem.\n- **Technology**: Eureka Server (Spring Cloud Netflix)\n- **Features**: Service discovery, registration management, and health monitoring.\n\n### 3. Product Service 🛒\n\n- **Description**: Manages the product catalog, including product details and inventory.\n- **Technology**: Spring Boot, MySQL, Redis\n- **Features**: CRUD operations for product data, inventory management, product caching.\n\n### 4. Order Service 🧾\n\n- **Description**: Oversees order processing, tracking, and history for users.\n- **Technology**: Spring Boot, MySQL, Zipkin\n- **Features**: Order creation, processing, status tracking, history management, tracing.\n\n### 5. Email Service 📧\n\n- **Description**: Manages sending email notifications for order confirmations, password resets, and other user communications.\n- **Technology**: Spring Boot, MySQL\n- **Features**: Sending emails, email templates, email scheduling, and delivery status tracking.\n\n### 6. Identity Service 🧑‍💻\n\n- **Description**: Handles user authentication, authorization, and identity management.\n- **Technology**: Spring Boot, MySQL, Redis\n- **Features**: User registration, login, role management, authentication tokens, session storage.\n\n### 7. Payment Service 💳\n\n- **Description**: Manages payment processing, transactions, and invoices.\n- **Technology**: Spring Boot, MySQL, Zipkin\n- **Features**: Payment processing, transaction history, invoice management, tracing.\n\n## Technologies Used 🔧\n\n- **Spring Boot**: The main framework for developing microservices.\n- **Apache Kafka**: Supports inter-service communication via asynchronous messaging.\n- **OpenFeign**: Simplifies HTTP calls between microservices with declarative REST clients.\n- **MySQL**: Relational database management system for storing service-specific data.\n- **Redis**: Temporary data storage and caching for high performance.\n- **Zipkin**: Distributed tracing tool for monitoring and debugging microservices.\n- **Spring Cloud**: Provides tools for managing a distributed system (Eureka, Gateway, etc.).\n- **Docker**: Containerizes each microservice to ensure consistent and isolated environments.\n- **Docker Compose**: Coordinates multi-container Docker applications, managing service dependencies and networking.\n\n## Project Setup 🛠️\n\n### 🛠️ **Requirements**\n\nEnsure you have the following installed on your development machine:\n\n- **Docker**: [Install Docker](https://docs.docker.com/get-docker/)\n- **Docker Compose**: [Install Docker Compose](https://docs.docker.com/compose/install/)\n- **Git**: To clone the repository.\n- **Web Browser**: To access service dashboards and APIs.\n\n### 🚀 **Clone Repository**\n\n```bash\ngit clone https://github.com/haphong463/springboot-kafka-microservices.git\ncd springboot-kafka-microservices\n```\n\n### 🐳 Run Microservices with Docker Compose\n\nThe project uses Docker Compose to manage all microservices and their dependencies. Follow these steps to boot up the system:\n\n#### Ensure Docker and Docker Compose are Running\n\nMake sure Docker Desktop (or Docker Engine) is running on your machine.\n\n#### Build and Start All Services\n\nFrom the project's root directory, execute:\n\n```bash\ndocker-compose up -d\n```\n\n**Flag:**\n- `-d`: Run containers in detached mode.\n\n#### Check All Services are Running\n\nCheck the status of all running containers:\n\n```bash\ndocker-compose ps\n```\n\n**Expected Result:**\n\n```\n    Name                      Command               State               Ports\n--------------------------------------------------------------------------------------------\napi-gateway            java -jar /app.jar            Up      0.0.0.0:9191-\u003e9191/tcp\neureka-server          java -jar /app.jar            Up      0.0.0.0:8761-\u003e8761/tcp\nidentity-service       java -jar /app.jar            Up      0.0.0.0:9898-\u003e9898/tcp\nkafka                  /etc/confluent/docker/run     Up      0.0.0.0:9092-\u003e9092/tcp, 0.0.0.0:29092-\u003e29092/tcp\nmysql-order-service    docker-entrypoint.sh mysqld   Up      0.0.0.0:3307-\u003e3306/tcp\nmysql-identity-service docker-entrypoint.sh mysqld   Up      0.0.0.0:3308-\u003e3306/tcp\nmysql-payment-service  docker-entrypoint.sh mysqld   Up      0.0.0.0:3309-\u003e3306/tcp\nmysql-product-service  docker-entrypoint.sh mysqld   Up      0.0.0.0:3310-\u003e3306/tcp\nredis                  docker-entrypoint.sh redis    Up      0.0.0.0:6379-\u003e6379/tcp\nzipkin                 start-zipkin                  Up      0.0.0.0:9411-\u003e9411/tcp\norder-service          java -jar /app.jar            Up      0.0.0.0:8080-\u003e8080/tcp\npayment-service        java -jar /app.jar            Up      0.0.0.0:8085-\u003e8085/tcp\nproduct-service        java -jar /app.jar            Up      0.0.0.0:8084-\u003e8084/tcp\nemail-service          java -jar /app.jar            Up      0.0.0.0:8081-\u003e8081/tcp\nzookeeper              /etc/confluent/docker/run     Up      0.0.0.0:2181-\u003e2181/tcp\n```\n\n### 🛠️ Service Configuration\n\nAll configurations are managed via environment variables defined in the `docker-compose.yml` file. However, if you need to customize configurations, you can edit the `application-docker.properties` or `application.yml` files in each microservice.\n\n#### Example: Configuring order-service in docker-compose.yml\n\n```yaml\norder-service:\n  image: springboot-kafka-microservices/order-service:latest\n  container_name: order-service\n  depends_on:\n    - kafka\n    - mysql-order-service\n    - eureka-server\n    - zipkin\n  ports:\n    - \"8080:8080\"\n  environment:\n    SPRING_DATASOURCE_URL: jdbc:mysql://mysql-order-service:3306/order_db?useSSL=false\u0026allowPublicKeyRetrieval=true\u0026serverTimezone=UTC\n    SPRING_DATASOURCE_USERNAME: root\n    SPRING_DATASOURCE_PASSWORD: root\n    SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092\n    EUREKA_CLIENT_SERVICEURL_DEFAULTZONE: http://eureka-server:8761/eureka/\n    SPRING_ZIPKIN_BASE_URL: http://zipkin:9411/\n    SPRING_PROFILES_ACTIVE: docker\n  networks:\n    - shop-network\n```\n\n- **SPRING_DATASOURCE_URL**: Connects to the `mysql-order-service` database.\n- **SPRING_KAFKA_BOOTSTRAP_SERVERS**: Specifies the Kafka broker within Docker.\n- **EUREKA_CLIENT_SERVICEURL_DEFAULTZONE**: Registers with the Eureka Server.\n- **SPRING_ZIPKIN_BASE_URL**: Configures Zipkin for tracing.\n\n## API Endpoints and Testing 🔍\n\n### 🛠️ Accessing Services\n\n- **Eureka Server Dashboard**: [http://localhost:8761](http://localhost:8761)\n  - Monitor registered services and their statuses.\n\n- **API Gateway**: [http://localhost:9191](http://localhost:9191)\n  - The entry point for all API requests.\n\n- **Zipkin Tracing UI**: [http://localhost:9411](http://localhost:9411)\n  - Interface for monitoring and analyzing service tracing.\n\n- **Order Service**: [http://localhost:8080](http://localhost:8080)\n\n- **Payment Service**: [http://localhost:8085](http://localhost:8085)\n\n- **Product Service**: [http://localhost:8084](http://localhost:8084)\n\n- **Email Service**: [http://localhost:8081](http://localhost:8081)\n\n- **Identity Service**: [http://localhost:9898](http://localhost:9898)\n\n### 🛠️ Testing APIs\n\nUse tools like Postman, Insomnia, or cURL to interact with the APIs. Below are examples of how to perform basic operations, considering the required role for each operation and using cookies for authentication:\n\n### 🛠️ User Registration and Authentication\n\nBelow are the steps and examples for registering a new user and obtaining authentication tokens using cookies.\n\n#### 🔐 User Registration\n\nTo register a new user, provide their name, password, email, and roles. Roles should be specified as an array and can include roles like `CUSTOMER`, `EMPLOYEE`, etc.\n\n**Endpoint**: `POST http://localhost:9191/api/v1/auth/register`\n\n```bash\ncurl -X POST http://localhost:9191/api/v1/auth/register \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n           \"name\": \"johndoe\",\n           \"password\": \"securepassword\",\n           \"email\": \"john.doe@example.com\",\n           \"roles\": [\"CUSTOMER\"]\n         }'\n```\n\n#### 🔑 Authentication (Login)\n\nTo log in and receive a session cookie, submit your username and password to the authentication endpoint. The server will return a cookie containing your session ID if the login is successful.\n\n**Endpoint**: `POST http://localhost:9191/api/v1/auth/token`\n\n```bash\ncurl -X POST http://localhost:9191/api/v1/auth/token \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n           \"username\": \"johndoe\",\n           \"password\": \"securepassword\"\n         }'\n```\n\nUse the session cookie stored in `cookies.txt` for subsequent requests that require authentication. This setup ensures secure handling of user sessions and simplifies credential management across multiple requests.\n\n#### 📦 Example of Product Service\n\n**Add New Product (Role Required: EMPLOYEE)**\n\nTo perform this operation, your user must be authenticated as an employee. Ensure your cookie with authentication details is included in the request.\n\n```bash\ncurl -X POST http://localhost:9191/api/v1/products \\\n     -H \"Content-Type: application/json\" \\\n     -b \"token=your_jwt_token\" \\\n     -d '{\n           \"name\": \"New Product\",\n           \"imageUrl\": \"image1.png\",\n           \"description\": \"Product description\",\n           \"price\": 99.99,\n           \"stockQuantity\": 100\n         }'\n```\n\n#### 🧾 Example of Order Service\n\n**Create New Order (Role Required: CUSTOMER)**\n\nTo perform this operation, your user must be authenticated as a customer. Ensure your cookie with authentication details is included in the request.\n\n```bash\ncurl -X POST http://localhost:9191/api/v1/order \\\n     -H \"Content-Type: application/json\" \\\n     -b \"token=your_jwt_token\" \\\n     -d '{\n            \"orderItems\": [\n                {\n                    \"productId\": \"02f6f017-816d-419f-a680-26f814be70e5\",\n                    \"quantity\": 1\n                }\n            ],\n            \"paymentMethod\": \"COD\"\n         }'\n```\n\n## Database Management 🗃️\n\nEach microservice has a separate MySQL database to ensure data isolation and integrity. Here's how you can manage them:\n\n### 🐳 Accessing MySQL Databases via Docker\n\n#### From Host Using MySQL Client\n\nYou can connect to any MySQL database using the host ports mapped in `docker-compose.yml`.\n\n**Example: Connect to `order_db`**\n\n```bash\nmysql -h 127.0.0.1 -P 3307 -u root -p\n```\n\n- **Host**: `127.0.0.1`\n- **Port**: `3307` (mapped to container port `3306`)\n- **Username**: `root`\n- **Password**: `root`\n\n#### From Inside the Docker Network\n\nServices can communicate with each other using service names and internal ports.\n\n**Example: Access `order_db` from `order-service`**\n\n```bash\nmysql -h mysql-order-service -P 3306 -u root -p\n```\n\n### 🐳 Using Docker Exec to Access MySQL Inside Container\n\n**Enter MySQL Container**\n\n```bash\ndocker exec -it mysql-order-service bash\n```\n\n**Connect to MySQL**\n\n```bash\nmysql -u root -proot order_db\n```\n\n- **Username**: `root`\n- **Password**: `root`\n- **Database**: `order_db`\n\n**Add Record to Role Table**\n\n```sql\nCREATE TABLE IF NOT EXISTS roles (\n    id INT AUTO_INCREMENT PRIMARY KEY,\n    name VARCHAR(50) NOT NULL UNIQUE\n);\n\nINSERT INTO roles (name) VALUES ('EMPLOYEE'), ('ADMINISTRATOR'), ('CUSTOMER');\n```\n\n**Check Records Have Been Successfully Added**\n\n```sql\nSELECT * FROM roles;\n```\n\n**Expected Result:**\n\n```\n+----+---------------+\n| id | name          |\n+----+---------------+\n|  1 | EMPLOYEE      |\n|  2 | ADMINISTRATOR |\n|  3 | CUSTOMER      |\n+----+---------------+\n```\n\n**Exit MySQL and Container**\n\n```bash\nEXIT;\nexit\n```\n\n## Troubleshooting 🛠️\n\n### ❗ Common Issues and Solutions\n\n#### Eureka Server Not Registering Services\n\n- **Issue**: Services not appearing on Eureka Dashboard.\n- **Solution**:\n  - Ensure the environment variable `EUREKA_CLIENT_SERVICEURL_DEFAULTZONE` is set correctly as `http://eureka-server:8761/eureka/` in `docker-compose.yml`.\n  - Check network connectivity between services.\n  - Check logs of both the service and Eureka Server for registration errors.\n\n#### Kafka Listener Port Conflict\n\n- **Issue**: `java.lang.IllegalArgumentException: requirement failed: Each listener must have a different port`\n- **Solution**:\n  - Update `KAFKA_ADVERTISED_LISTENERS` to use different ports for each listener in `docker-compose.yml`.\n\n  **Example:**\n\n  ```yaml\n  KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092\n  ```\n\n#### MySQL Volume Not Defined\n\n- **Issue**: Service \"mysql-product-service\" refers to undefined volume `mysql-product-service-data`\n- **Solution**:\n  - Define all necessary volumes in the `volumes` section of `docker-compose.yml`.\n\n  ```yaml\n  volumes:\n    mysql-order-service-data:\n    mysql-identity-service-data:\n    mysql-payment-service-data:\n    mysql-product-service-data:\n  ```\n\n#### Service Not Starting\n\n- **Issue**: Service containers crashing or not starting.\n- **Solution**:\n  - Check logs of the specific service:\n\n    ```bash\n    docker-compose logs -f \u003cservice-name\u003e\n    ```\n  - Ensure environment variables are set correctly.\n  - Check database connections and login details.\n\n#### Port Conflict on Host\n\n- **Issue**: Host ports being used by another service.\n- **Solution**:\n  - Change host port mappings in `docker-compose.yml` to unused ports.\n\n  **Example:**\n\n  ```yaml\n  ports:\n    - \"3306:3306\"    # Change to \"3312:3306\" if 3306 is being used\n  ```\n\n### 🔍 Checking Logs\n\nUse Docker Compose to view logs of any service:\n\n```bash\ndocker-compose logs -f \u003cservice-name\u003e\n```\n\n**Example: View Logs of `eureka-server`**\n\n```bash\ndocker-compose logs -f eureka-server\n```\n\n### 🐳 Rebuilding Containers\n\nIf you make changes to the code or configurations, rebuild and restart the affected services:\n\n```bash\ndocker-compose up -d --build \u003cservice-name\u003e\n```\n\n**Example: Rebuild and Restart `order-service`**\n\n```bash\ndocker-compose up -d --build order-service\n```\n\n## Useful Documentation 📚\n\n- [Spring Boot Documentation](https://spring.io/projects/spring-boot)\n- [Spring Cloud Documentation](https://spring.io/projects/spring-cloud)\n- [Apache Kafka Documentation](https://kafka.apache.org/documentation/)\n- [Redis Documentation](https://redis.io/documentation)\n- [Zipkin Documentation](https://zipkin.io/pages/documentation.html)\n- [Docker Documentation](https://docs.docker.com/)\n- [Docker Compose Documentation](https://docs.docker.com/compose/)\n- [Eureka Server Documentation](https://cloud.spring.io/spring-cloud-netflix/multi/multi__service_discovery_eureka_clients.html)\n- [Spring Cloud Gateway Documentation](https://spring.io/projects/spring-cloud-gateway)\n\n## License 📝\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaphong463%2Fspringboot-kafka-microservices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaphong463%2Fspringboot-kafka-microservices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaphong463%2Fspringboot-kafka-microservices/lists"}