Running the Application
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive guide to setting up and running the e-commerce microservices platform. The project is built with NestJS in a monorepo structure, utilizing NATS for inter-service communication and PostgreSQL with Prisma for data persistence.
There are two primary methods for running the application: a local development setup for coding and debugging, and a Docker-based deployment for production or staging environments. Both methods are detailed below. For more information on the system's architecture, see the Architecture Overview.
Sources: README.md:19-25, SETUP.md:3-8, deploys/README.md:11-29
Local Development Setup
This setup is designed for developers to run all microservices on a local machine with hot-reloading enabled. It uses Docker Compose to manage infrastructure dependencies like databases and NATS.
Sources: SETUP.md
Prerequisites
Before starting, ensure you have the following installed:
- Node.js: v20+ (v20.11.0 recommended)
- pnpm: v8+
- Docker: v24+ with Docker Compose
Sources: SETUP.md:4-8
Setup and Execution Flow
The following diagram illustrates the step-by-step process for getting the application running locally.
This diagram shows the sequence of commands to run the application in a local development environment.
Sources: SETUP.md:12-50, package.json:8-44
Detailed Steps
-
Install Dependencies:
pnpm installSources: SETUP.md:12, package.json:44
-
Setup Environment Variables: Copy the example environment file and update it. A strong
JWT_SECRET_KEYis required.cp .env.example .env nano .envSources: SETUP.md:17-27
-
Generate RSA Keys: The system uses an asymmetric RSA-based JWT for authentication. The
user-appsigns tokens with the private key, and other services verify with the public key.pnpm run generate:keysThis creates
private-key.pemandpublic-key.pemin thekeys/directory.
Sources: SETUP.md:29-38, package.json:33 -
Start Infrastructure: Use Docker Compose to start all PostgreSQL databases and the NATS message broker.
docker compose up -dSources: SETUP.md:41-46
-
Run Database Migrations: This command generates Prisma clients and applies migrations to all service databases.
pnpm db:migrate:allSources: SETUP.md:48-53, package.json:31
-
Start All Services: Run all microservices concurrently in watch mode for development.
pnpm dev:allThe gateway will be available at
http://localhost:3000and the NATS monitor athttp://localhost:8222.
Sources: SETUP.md:55-61, package.json:11
Key pnpm Scripts
The package.json file defines several scripts for managing the application lifecycle.
| Script | Description |
|---|---|
dev:all | Starts all applications in watch mode for development. |
start:prod:all | Starts all applications from their compiled dist output. |
build:all | Builds all applications using the NestJS CLI. |
test | Runs all unit tests. |
test:e2e | Runs all end-to-end tests. |
db:migrate:all | Applies database migrations for all services. |
db:reset:all | Resets and reapplies all migrations for all services. |
generate:keys | Generates RSA public/private key pair for JWT. |
Sources: package.json:7-44
Docker Deployment
This method is intended for staging or production environments. It involves building Docker images for each service, pushing them to a registry, and deploying them to one or more hosts.
Sources: deploys/README.md, QUICK_START.md
Architecture Overview
The deployment architecture consists of multiple hosts, a central Docker registry, a dedicated PostgreSQL server, and a NATS server.
This diagram shows how services are built, pushed to a registry, and pulled by various hosts that connect to shared database and messaging servers.
Sources: deploys/README.md:11-29
One-Time Infrastructure Setup
Before the first deployment, the following infrastructure must be set up:
- PostgreSQL Server: A single host running PostgreSQL. All microservice databases (
user_db,product_db, etc.) are created on this server.
Sources: deploys/README.md:69-83, QUICK_START.md:29-30 - NATS Server: A single host running the NATS message broker for inter-service communication.
Sources: deploys/README.md:85-94, QUICK_START.md:32-33 - Docker Hub: An account is needed to store and distribute the Docker images.
Sources: deploys/README.md:96-103
Deployment Flow
The deployment process involves building images, pushing them to a registry, and then deploying them on target hosts.
This diagram outlines the full lifecycle from generating database migrations to deploying a specific application on a host.
Sources: QUICK_START.md:11-27, deploys/README.md:37-133
Build and Push Images
The project includes scripts to automate building and pushing all service images.
-
Generate Initial Migrations: Before building, generate the initial database migrations. This is a critical one-time step.
pnpm run db:migrate:all git add apps/*/prisma/migrations/ git commit -m "chore: initial migrations" git pushSources: QUICK_START.md:12-17, deploys/README.md:37-67
-
Build and Push: Set your Docker Hub username and a version tag, then run the scripts.
export DOCKER_USERNAME=your_docker_username export VERSION=v1.0.0 ./scripts/build-all-images.sh ./scripts/push-all-images.shThese scripts are also integrated into the CI/CD pipeline.
Sources: QUICK_START.md:20-27, deploys/README.md:108-126, CI_CD_SETUP.md:5-19
Deploying on a Host
On each deployment host:
- Clone the repository and navigate to the
deploysdirectory. - Create and configure the
.envfile with the correctDOCKER_USERNAME,VERSION,NATS_URL, andDATABASE_URL_*variables. - Run the deployment script for the specific service.
./deploy.sh user-app
Sources: QUICK_START.md:35-47, deploys/README.md:135-180
Docker Entrypoint
The Docker images use an entrypoint script (scripts/docker-entrypoint.sh) that performs two key actions before starting the application:
- Run Migrations: It automatically runs
npx prisma migrate deployto apply any pending database migrations for the specific service. - Generate Keys (user-app only): For the
user-app, it generates the RSA key pair if they don't already exist. - Start Application: It executes the main application entrypoint (
node dist/apps/<APP_NAME>/main.js).
Sources: scripts/docker-entrypoint.sh, docker/README.md:72-74
Critical Startup Order
For the system to function correctly, services must be started in a specific order to prevent JWT and connection errors.
This diagram shows the required startup sequence: PostgreSQL, then NATS, followed by user-app (which publishes the JWT key), then the gateway (which needs the key), and finally all other services.
Sources: QUICK_START.md:73-82, deploys/README.md:182-192
Configuration (.env)
The .env file in the deploys/ directory centralizes configuration for all services.
| Variable | Description | Example |
|---|---|---|
DOCKER_USERNAME | Your Docker Hub username. | myusername |
VERSION | The version tag of the images to pull. | v1.0.0 |
NATS_URL | The connection URL for the NATS server. | nats://nats-server-ip:4222 |
DATABASE_URL_USER | Connection string for the user service database. | postgresql://user:pass@db:5432/user_db |
DATABASE_URL_PRODUCT | Connection string for the product service database. | postgresql://user:pass@db:5432/product_db |
CORS_ORIGIN | Allowed origins for the API Gateway. | http://localhost:3001,https://mydomain.com |
Sources: QUICK_START.md:52-64, deploys/README.md:196-217
Testing the Application
The repository includes scripts for running unit and end-to-end (E2E) tests.
- Unit Tests: Run with
pnpm test. This executes all*.spec.tsfiles using Jest. - E2E Tests: Run with
pnpm test:e2e. This typically requires a running instance of the application or mocked services. A full E2E test suite that manages its own test containers can be run withpnpm test:full.
Sources: package.json:17-23, 35-41, SETUP.md:65-82