Skip to content

Commit 77ef59a

Browse files
KettailorKettailor
authored
Merge pull request #6 from Kettailor/codex/update-readme,-license,-and-workflow-status
Add documentation and licensing information
2 parents 1e7caa9 + 336ad1d commit 77ef59a

File tree

3 files changed

+143
-2
lines changed

3 files changed

+143
-2
lines changed

‎LICENSE‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
ISC License
2+
3+
Copyright (c) 2024, Tran Le Kiet
4+
5+
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

‎README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# EProject Microservices Platform
2+
3+
[![CI/CD](https://github.com/TranLeKiet/EProject/actions/workflows/ci.yml/badge.svg)](https://github.com/TranLeKiet/EProject/actions/workflows/ci.yml)
4+
5+
EProject is a learning-oriented microservices environment that demonstrates how an e-commerce style workflow can be decomposed into independent Node.js services. It showcases authentication, catalog management, order processing, and an API gateway, all orchestrated with Docker Compose and backed by MongoDB and RabbitMQ.
6+
7+
## Features
8+
9+
- **Authentication service** for registering users, issuing JWTs, and protecting secured routes.
10+
- **Product service** that maintains product data and publishes product-related messages to RabbitMQ.
11+
- **Order service** that consumes product events, persists orders, and coordinates with RabbitMQ queues.
12+
- **API Gateway** that forwards external traffic to the individual services and centralises routing.
13+
- **Shared tooling** for testing with Mocha/Chai and end-to-end automation through GitHub Actions.
14+
15+
## Architecture
16+
17+
| Component | Description | Default Port |
18+
| --- | --- | --- |
19+
| `auth` | Handles user registration, login, and token validation against MongoDB. | `3000` |
20+
| `product` | Manages the product catalogue and publishes events through RabbitMQ. | `3001` |
21+
| `order` | Accepts customer orders and reacts to product events via RabbitMQ. | `3002` |
22+
| `api-gateway` | Express + http-proxy entry point that routes `/auth`, `/products`, and `/orders` traffic. | `3003` |
23+
| `mongo` | MongoDB instance that stores data for the services. | `27017` |
24+
| `rabbitmq` | Message broker used for asynchronous communication between services. | `5672` (AMQP) / `15672` (management UI) |
25+
26+
The services communicate via REST over HTTP and publish/consume events on shared RabbitMQ queues (`orders`, `products`). Configuration defaults are provided in each service but can be overridden with environment variables.
27+
28+
```
29+
.
30+
├── api-gateway # Reverse proxy and routing layer
31+
├── auth # Authentication service (MongoDB + JWT)
32+
├── order # Order processing service (MongoDB + RabbitMQ consumer)
33+
├── product # Product catalogue service (MongoDB + RabbitMQ publisher)
34+
├── utils # Utility libraries shared between services
35+
├── docker-compose.yml # Spins up all services plus MongoDB & RabbitMQ
36+
└── .github/workflows # Continuous integration pipeline definition
37+
```
38+
39+
## Getting Started
40+
41+
### Prerequisites
42+
43+
- [Node.js 18+](https://nodejs.org/) for running services locally and executing tests.
44+
- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) for containerised development.
45+
- (Optional) An existing MongoDB and RabbitMQ instance if you do not rely on Docker Compose.
46+
47+
### Environment configuration
48+
49+
Each service reads its configuration from environment variables with sensible defaults:
50+
51+
- `auth`: `PORT`, `MONGODB_AUTH_URI`, `JWT_SECRET`.
52+
- `product`: `PORT`, `MONGODB_PRODUCT_URI`, `RABBITMQ_URI`, `RABBITMQ_ORDER_QUEUE`, `RABBITMQ_PRODUCT_QUEUE`, `JWT_SECRET`, `RABBITMQ_CONNECT_DELAY_MS`.
53+
- `order`: `PORT`, `MONGODB_ORDER_URI`, `RABBITMQ_URI`, `RABBITMQ_ORDER_QUEUE`, `RABBITMQ_PRODUCT_QUEUE`, `JWT_SECRET`, `RABBITMQ_CONNECT_DELAY_MS`.
54+
- `api-gateway`: `PORT`, `AUTH_SERVICE_URL`, `PRODUCT_SERVICE_URL`, `ORDER_SERVICE_URL` or their respective `_HOST`/`_PORT` overrides.
55+
56+
Copy the required variables into `.env` files under each service (e.g. `auth/.env`, `product/.env`, etc.) before running the stack.
57+
58+
### Run with Docker Compose
59+
60+
1. Ensure Docker is running.
61+
2. Build and start the full stack:
62+
63+
```bash
64+
docker compose up --build
65+
```
66+
67+
3. Access the services through the API gateway at `http://localhost:3003`. The gateway proxies requests to `/auth`, `/products`, and `/orders`.
68+
69+
4. Stop the stack when you are done:
70+
71+
```bash
72+
docker compose down
73+
```
74+
75+
### Run services locally (without Docker)
76+
77+
Each service can also be started from the host machine:
78+
79+
```bash
80+
# From the repository root
81+
npm install
82+
83+
# Install dependencies inside individual services if needed
84+
npm install --prefix auth
85+
npm install --prefix product
86+
npm install --prefix order
87+
npm install --prefix api-gateway
88+
89+
# Start a service
90+
npm start --prefix auth
91+
```
92+
93+
Ensure MongoDB and RabbitMQ are available locally (the defaults assume `localhost`).
94+
95+
## Testing
96+
97+
Run the service-level test suites with Mocha/Chai via the repository root:
98+
99+
```bash
100+
npm test
101+
```
102+
103+
You can also target a specific service:
104+
105+
```bash
106+
npm test --prefix auth
107+
npm test --prefix product
108+
npm test --prefix order
109+
```
110+
111+
## Continuous Integration
112+
113+
GitHub Actions runs the workflow defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) on each push and pull request. The pipeline:
114+
115+
1. Checks out the repository and sets up Node.js 18 with npm caching.
116+
2. Installs dependencies and executes the shared test suite (`npm ci && npm test`).
117+
3. Builds Docker images for every service to catch Dockerfile regressions.
118+
4. On pushes to `main` or `master`, logs in to Docker Hub (using repository secrets) and pushes tagged images for each service.
119+
120+
You can manually trigger the pipeline or monitor its status from the **Actions** tab in GitHub. The status badge at the top of this README reflects the most recent workflow run.
121+
122+
## Troubleshooting
123+
124+
- RabbitMQ services may need a few seconds to accept connections. Adjust `RABBITMQ_CONNECT_DELAY_MS` in the service `.env` files if you encounter connection failures during startup.
125+
- If Docker builds cannot authenticate to Docker Hub, double-check that the `DOCKER_NAME` and `DOCKER_TOKEN` secrets are configured in your GitHub repository settings.
126+
- Remove `node_modules` directories before rebuilding containers if you experience mismatched native dependencies.
127+
128+
## License
129+
130+
This project is licensed under the [ISC License](LICENSE).
131+
132+
## Contributing
133+
134+
Issues and pull requests are welcome! Please open a ticket describing the change, ensure tests pass locally, and link to any relevant GitHub Actions runs.

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
{
22
"name": "EProject",
33
"version": "1.0.0",
4-
"description": "",
4+
"description": "Microservices e-commerce demo with Node.js, MongoDB, and RabbitMQ",
55
"main": "index.js",
66
"scripts": {
77
"test": "mocha --timeout 20000 --recursive --exclude '**/node_modules/**' '**/*.test.js' --exit"
88
},
99
"keywords": [],
10-
"author": "",
10+
"author": "Tran Le Kiet",
1111
"license": "ISC",
1212
"dependencies": {
1313
"amqplib": "^0.10.3",

0 commit comments

Comments
 (0)