Project Setup

Relevant source files

The following files were used as context for generating this wiki page:

• SETUP.md
• package.json
• deploys/README.md
• nest-cli.json
• QUICK_START.md
• scripts/docker-entrypoint.sh
• deploys/deploy.sh

This document provides a comprehensive guide to setting up the e-commerce microservices project for both local development and Docker-based deployment. The project is a NestJS-based monorepo utilizing a microservices architecture with NATS for communication and PostgreSQL for data persistence.

The setup process involves initializing dependencies, configuring environment variables, starting infrastructure services with Docker, running database migrations, and finally, launching the applications. Following these steps will create a fully functional local environment that mirrors the production architecture. For more details on deployment, see the Docker Deployment Guide.

Prerequisites

Before starting, ensure the following tools are installed on your system:

Tool	Version	Installation Command
Node.js	v20+	(Use nvm or installer)
pnpm	v8+	npm install -g pnpm
Docker	v24+	(Install Docker Desktop)
PostgreSQL Client	(Any)	(Optional, for DB access)

Sources: SETUP.md:3-8

Local Development Setup

This section details the step-by-step process to get the entire microservices platform running on your local machine.

Setup Workflow

The following diagram illustrates the high-level workflow for local setup.

1. Install Dependencies

First, install all project dependencies using pnpm.

pnpm install

Sources: SETUP.md:12, package.json:115-116

2. Configure Environment Variables

Copy the example environment file to create your local configuration.

cp .env.example .env

After copying, you must update the JWT_SECRET_KEY in the .env file with a strong, unique secret of at least 32 characters. The database URLs are pre-configured for the local Docker setup.

Sources: SETUP.md:16-25

3. Generate RSA Keys

The system uses asymmetric RSA keys for JWT signing and verification. The user-app signs tokens with the private key, and all other services verify them with the public key. Generate the default key pair:

pnpm run generate:keys

This command creates a keys/ directory in the project root containing private-key.pem and public-key.pem.

Sources: SETUP.md:28-38, package.json:66

4. Start Infrastructure Services

The project relies on Docker to run NATS and the PostgreSQL databases. Start these services in detached mode:

docker compose up -d

This command uses the docker-compose.yml file to spin up the following services:

• A NATS message broker.
• A separate PostgreSQL database container for each microservice.

You can monitor the startup progress with docker compose logs -f.

Sources: SETUP.md:41-45

5. Run Database Migrations

Once the databases are running, apply the database schemas for all microservices. This process involves two steps:

1. Generate Prisma Clients: This ensures each service's code has the types for its database schema.
2. Run Migrations: This applies the SQL migration files to each database.

# Generate Prisma clients
pnpm db:gen:all

# Run migrations for all services
pnpm db:migrate:all

Sources: SETUP.md:48-54, package.json:62-64

6. Start All Microservices

With the infrastructure and databases ready, start all applications in development watch mode.

pnpm dev:all

This command concurrently starts the gateway and all microservices, enabling hot-reloading on code changes.

Sources: SETUP.md:57-64, package.json:14

7. Verify Services

After startup, you can verify that the core services are running by accessing their endpoints:

• API Gateway: http://localhost:3000/health
• NATS Monitor: http://localhost:8222

Sources: SETUP.md:67-69

Project Structure

The project is a NestJS monorepo, which organizes multiple applications and libraries within a single repository. The structure is defined in nest-cli.json.

The apps/ directory contains each microservice and the API gateway. The libs/ directory contains shared code, such as DTOs and type definitions, used across multiple applications.

Sources: nest-cli.json

Key pnpm Scripts

The package.json file contains numerous scripts to streamline development tasks.

Command	Description
pnpm dev:all	Starts all applications in watch mode for development.
pnpm test	Runs all unit tests.
pnpm test:e2e	Runs all end-to-end tests.
pnpm lint	Lints and fixes all TypeScript files.
pnpm db:gen:all	Generates Prisma clients for all applications.
pnpm db:migrate:all	Creates and applies new database migrations for all applications.
pnpm db:reset:all	Resets all databases and re-applies all migrations.
pnpm generate:keys	Generates the RSA public/private key pair for JWT authentication.

Sources: package.json:8-70

Docker-based Deployment Setup

The setup for a production-like environment using Docker is different from the local development flow. It involves building container images for each service, pushing them to a registry, and deploying them to one or more hosts.

Deployment Architecture

The following diagram shows the high-level architecture for a Docker-based deployment.

Deployment Workflow

1. Generate Migrations: Before building images, initial database migrations must be generated and committed to the repository.

   pnpm run db:migrate:all
   git add apps/*/prisma/migrations/
   git commit -m "chore: initial migrations"
   

2. Setup Infrastructure: A central PostgreSQL server and a NATS server must be running and accessible to the application hosts.
3. Build & Push Images: Use the provided scripts to build all service images and push them to a Docker registry like Docker Hub.
4. Deploy Services: On each host, clone the repository, configure the .env file with the correct database and NATS connection strings, and run the deployment script for the specific service.

   # On a deployment host
   git clone <repo>
   cd backend-luan-van/deploys
   cp .env.example .env
   nano .env
   ./deploy.sh user-app
   

Sources: QUICK_START.md:9-35, deploys/README.md:41-61, 118-133, deploys/deploy.sh

Container Entrypoint

When a microservice container starts, the docker-entrypoint.sh script is executed. This script performs two key actions before starting the Node.js application:

1. Run Migrations: It automatically runs npx prisma migrate deploy to apply any pending database migrations.
2. Generate Keys (user-app only): If the service is user-app and JWT keys do not exist, it generates them.

This ensures that the database is up-to-date and the user-app is ready to sign tokens upon startup.

Sources: scripts/docker-entrypoint.sh