Building Scalable Microservices with NestJS and Docker

Introduction

Microservices have become the de‑facto standard for building large‑scale, maintainable applications. By splitting a monolith into independently deployable services, teams gain autonomy, fault isolation, and the ability to scale individual components. NestJS, a progressive Node.js framework built with TypeScript, provides a modular architecture that maps naturally to the microservice paradigm. Combined with Docker, each service can be packaged with its exact runtime dependencies, ensuring consistency from development to production.

In this article you will learn how to design a microservice system, implement core services with NestJS, containerize them with Docker, wire them together using an API gateway, and prepare the whole stack for scalable deployment. Every section contains production‑ready code snippets, configuration files, and practical advice drawn from real‑world projects.

Table of Contents

• Introduction
• Core Concepts
• Architecture Overview
• Step‑by‑Step Guide
• Real‑World Examples
• Production Code Examples
• Comparison Table
• Best Practices
• Common Mistakes
• Performance Tips
• Security Considerations
• Deployment Notes
• Debugging Tips
• FAQ
• Conclusion

Core Concepts

Microservice Boundaries

Define each service around a single business capability. Typical boundaries include User Management, Order Processing, Payment, and Notification. Each service owns its data store and exposes a well‑defined API (REST, GraphQL, or message‑based).

Communication Patterns

• Synchronous: HTTP/REST or gRPC for request‑response flows.
• Asynchronous: Message brokers (RabbitMQ, Kafka, NATS) for event‑driven interactions.

Service Discovery

In a containerized environment services need to locate each other dynamically. Docker Compose provides built‑in DNS based on service names; in Kubernetes you would use CoreDNS and Service resources.

API Gateway

A single entry point routes external traffic to internal services, handles cross‑cutting concerns (authentication, rate limiting, logging) and can aggregate responses.

Observability

Structured logging, distributed tracing (OpenTelemetry), and metrics (Prometheus) are essential for operating microservices at scale.

Architecture Overview

The reference architecture consists of the following components:

• API Gateway (NestJS + @nestjs/platform-express or fastify)
• User Service (NestJS, PostgreSQL, TypeORM)
• Order Service (NestJS, MongoDB, Mongoose)
• Payment Service (NestJS, external Stripe SDK)
• Notification Service (NestJS, RabbitMQ consumer)
• Message Broker (RabbitMQ)
• Database per Service (PostgreSQL, MongoDB)
• Reverse Proxy / Load Balancer (NGINX or Traefik)

Each service lives in its own Git repository (or monorepo folder) with an independent Dockerfile and docker-compose.yml for local development. The gateway aggregates Swagger docs from all services for a unified developer portal.

Step‑by‑Step Guide

1. Scaffold the Monorepo

mkdir microservices-nestjs-dockercd microservices-nestjs-dockernpm init -ynpm install -g @nestjs/clinest new gateway --package-manager npmnest new user-service --package-manager npmnest new order-service --package-manager npmnest new payment-service --package-manager npmnest new notification-service --package-manager npm

Each nest new creates a standalone NestJS project with its own package.json, tsconfig.json, and test setup.

2. Configure Shared Libraries

Create a libs folder for shared DTOs, interfaces, and utility functions. Publish them as private npm packages or use TypeScript path aliases.

mkdir libscd libsnest generate library common --buildablenest generate library dto --buildable

3. Define Service Contracts

In libs/dto create Data Transfer Objects used across services. Example create-user.dto.ts:

export class CreateUserDto {  @IsEmail()  email: string;  @MinLength(8)  password: string;  @IsString()  fullName: string;}

4. Implement User Service

Install dependencies: npm i @nestjs/typeorm typeorm pg class-validator class-transformer. Configure TypeOrmModule in app.module.ts using environment variables.

// user-service/src/app.module.tsimport { Module } from '@nestjs/common';import { TypeOrmModule } from '@nestjs/typeorm';import { User } from './user.entity';import { UserService } from './user.service';import { UserController } from './user.controller';@Module({  imports: [    TypeOrmModule.forRootAsync({      useFactory: () => ({        type: 'postgres',        host: process.env.DB_HOST,        port: parseInt(process.env.DB_PORT || '5432', 10),        username: process.env.DB_USER,        password: process.env.DB_PASS,        database: process.env.DB_NAME,        entities: [User],        synchronize: process.env.NODE_ENV !== 'production',      }),    }),    TypeOrmModule.forFeature([User]),  ],  providers: [UserService],  controllers: [UserController],})export class AppModule {}

5. Containerize Each Service

Create a Dockerfile in each service root:

# user-service/DockerfileFROM node:20-alpine AS builderWORKDIR /appCOPY package*.json ./RUN npm ciCOPY . .RUN npm run buildFROM node:20-alpineWORKDIR /appENV NODE_ENV=productionCOPY --from=builder /app/dist ./distCOPY --from=builder /app/node_modules ./node_modulesCOPY package*.json ./EXPOSE 3000CMD ["node", "dist/main"]

Create a docker-compose.yml at the repo root for local development:

version: '3.8'services:  gateway:    build: ./gateway    ports:      - "3000:3000"    environment:      - USER_SERVICE_URL=http://user-service:3001      - ORDER_SERVICE_URL=http://order-service:3002    depends_on:      - user-service      - order-service  user-service:    build: ./user-service    expose:      - "3001"    environment:      - DB_HOST=postgres      - DB_PORT=5432      - DB_USER=postgres      - DB_PASS=postgres      - DB_NAME=user_db    depends_on:      - postgres  order-service:    build: ./order-service    expose:      - "3002"    environment:      - MONGO_URI=mongodb://mongo:27017/order_db    depends_on:      - mongo  postgres:    image: postgres:16-alpine    environment:      - POSTGRES_USER=postgres      - POSTGRES_PASSWORD=postgres      - POSTGRES_DB=user_db    volumes:      - pgdata:/var/lib/postgresql/data  mongo:    image: mongo:7-alpine    volumes:      - mongodata:/data/db  rabbitmq:    image: rabbitmq:3-management-alpine    ports:      - "5672:5672"      - "15672:15672"volumes:  pgdata:  mongodata:

6. Implement API Gateway Routing

Use HttpModule or a custom proxy middleware to forward requests. Example gateway/src/app.controller.ts:

import { Controller, Get, Post, Body, Inject, HttpService } from '@nestjs/common';import { ClientProxy, ClientProxyFactory, Transport } from '@nestjs/microservices';import { firstValueFrom } from 'rxjs';@Controller()export class AppController {  private userClient: ClientProxy;  private orderClient: ClientProxy;  constructor() {    this.userClient = ClientProxyFactory.create({      transport: Transport.TCP,      options: { host: 'user-service', port: 3001 },    });    this.orderClient = ClientProxyFactory.create({      transport: Transport.TCP,      options: { host: 'order-service', port: 3002 },    });  }  @Post('users')  async createUser(@Body() dto: any) {    return firstValueFrom(this.userClient.send({ cmd: 'create_user' }, dto));  }  @Post('orders')  async createOrder(@Body() dto: any) {    return firstValueFrom(this.orderClient.send({ cmd: 'create_order' }, dto));  }}

7. Add Asynchronous Communication

Install @nestjs/microservices and amqplib. In notification-service listen to a RabbitMQ queue:

// notification-service/src/notification.listener.tsimport { Controller } from '@nestjs/common';import { MessagePattern, Payload } from '@nestjs/microservices';@Controller()export class NotificationListener {  @MessagePattern('order.created')  async handleOrderCreated(@Payload() data: any) {    console.log('Sending email for order', data.orderId);    // integrate with SendGrid, nodemailer, etc.  }}

Publish events from Order Service after persisting:

// order-service/src/order.service.tsimport { Inject, Injectable } from '@nestjs/common';import { ClientProxy } from '@nestjs/microservices';@Injectable()export class OrderService {  constructor(@Inject('RABBITMQ_CLIENT') private client: ClientProxy) {}  async create(dto: any) {    const order = await this.saveOrder(dto);    this.client.emit('order.created', { orderId: order.id, ...dto });    return order;  }}

8. Configure CI/CD

Use GitHub Actions to build Docker images, run tests, and push to a registry (GHCR, Docker Hub, or cloud provider). Example workflow snippet:

name: CIon: [push]jobs:  build:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Set up Docker Buildx        uses: docker/setup-buildx-action@v3      - name: Build and push gateway        uses: docker/build-push-action@v5        with:          context: ./gateway          push: true          tags: ghcr.io/${{ github.repository }}/gateway:${{ github.sha }}      # repeat for each service

Real‑World Examples

E‑Commerce Platform

A mid‑size retailer split their monolith into five services (Catalog, Cart, Checkout, Payment, Shipping). Using the pattern above they achieved independent deployments, reduced release cycle from weeks to days, and scaled the Checkout service horizontally during flash sales.

SaaS Dashboard

A B2B analytics product isolated the data‑ingestion pipeline into a dedicated service communicating via Kafka. The NestJS consumer processes millions of events per hour while the API gateway serves low‑latency queries to the front‑end.

Production Code Examples

Health Check Endpoint

// common/health.controller.tsimport { Controller, Get } from '@nestjs/common';import { HealthCheck, HealthCheckService, TypeOrmHealthIndicator } from '@nestjs/terminus';@Controller('health')export class HealthController {  constructor(    private health: HealthCheckService,    private db: TypeOrmHealthIndicator,  ) {}  @Get()  @HealthCheck()  check() {    return this.health.check([      () => this.db.pingCheck('database'),    ]);  }}

Global Exception Filter

// common/all-exceptions.filter.tsimport { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';import { Request, Response } from 'express';@Catch()export class AllExceptionsFilter implements ExceptionFilter {  catch(exception: unknown, host: ArgumentsHost) {    const ctx = host.switchToHttp();    const response = ctx.getResponse();    const request = ctx.getRequest();    const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;    const message = exception instanceof HttpException ? exception.getResponse() : 'Internal server error';    response.status(status).json({      statusCode: status,      timestamp: new Date().toISOString(),      path: request.url,      message,    });  }}

Docker Multi‑Stage Build for Small Images

# payment-service/DockerfileFROM node:20-alpine AS depsWORKDIR /appCOPY package*.json ./RUN npm ci --only=productionFROM node:20-alpine AS builderWORKDIR /appCOPY package*.json ./RUN npm ciCOPY . .RUN npm run buildFROM node:20-alpine AS runnerWORKDIR /appENV NODE_ENV=productionCOPY --from=deps /app/node_modules ./node_modulesCOPY --from=builder /app/dist ./distCOPY package*.json ./EXPOSE 3000CMD ["node", "dist/main"]

Comparison Table

Best Practices

• Domain‑Driven Design: Model bounded contexts before writing code.
• Versioned APIs: Prefix routes with /v1/ and maintain backward compatibility.
• Idempotent Operations: Design POST/PUT endpoints to be safely retried.
• Centralized Config: Use a config service (Consul, Spring Cloud Config, or simple env files) rather than hard‑coding.
• Contract Testing: Implement Pact tests between gateway and services.
• Database per Service: Avoid shared databases to preserve loose coupling.
• Graceful Shutdown: Listen for SIGTERM, finish in‑flight requests, close DB connections.
• Automated Migrations: Run TypeORM/Mongoose migrations in CI before deployment.

Common Mistakes

1. Over‑splitting: Creating too many nano‑services increases latency and operational burden.
2. Shared Database: Couples services at the data layer, defeating independence.
3. Synchronous Chains: Long HTTP call chains cause cascading failures; prefer async events.
4. Ignoring Observability: Without logs/traces debugging distributed failures is near impossible.
5. Hard‑coded Service URLs: Use service discovery or environment variables.
6. No Contract Tests: Breaking changes slip into production.
7. Large Docker Images: Include dev dependencies; use multi‑stage builds.
8. Skipping Health Checks: Orchestrators cannot route traffic away from unhealthy containers.

Performance Tips

• Enable fastify adapter in NestJS for higher throughput.
• Use connection pooling for databases (TypeORM poolSize, Mongoose maxPoolSize).
• Cache frequently read data with Redis (e.g., user sessions, product catalog).
• Implement pagination and cursor‑based navigation for large collections.
• Compress HTTP responses with compression middleware.
• Leverage HTTP/2 on the gateway for multiplexed streams.
• Profile Node.js event loop latency with clinic.js or 0x.

Security Considerations

• Validate all inbound DTOs with class-validator and ValidationPipe.
• Implement JWT authentication in the gateway; propagate user context via headers to downstream services.
• Use TLS everywhere: terminate at the reverse proxy, enforce https between services (mTLS with Istio or Linkerd).
• Apply rate limiting per IP and per user (e.g., @nestjs/throttler).
• Sanitize logs – never log passwords, tokens, or PII.
• Regularly scan Docker images for vulnerabilities (trivy, grype).
• Rotate secrets via Vault or cloud secret manager; never bake them into images.

Deployment Notes

Kubernetes

Define a Deployment and Service for each microservice. Use HorizontalPodAutoscaler based on CPU/memory or custom metrics (queue length). Ingress controller (NGINX, Traefik) handles external routing and TLS termination.

Helm Charts

Package each service as a Helm chart with configurable values (replica count, resource limits, env vars). A top‑level umbrella chart can deploy the whole stack with a single helm install.

Blue‑Green / Canary

Leverage Argo Rollouts or Flagger for progressive delivery. Route a small percentage of traffic to the new version, monitor error rates, then promote.

Database Migrations

Run migrations as a Kubernetes Job before the main deployment starts. Use init containers or a dedicated migration chart.

Debugging Tips

• Attach VS Code debugger to a running container via inspect port (expose 9229).
• Use kubectl port-forward to access service ports locally.
• Enable NestJS request logging (Logger.log in an interceptor) with correlation IDs.
• Inspect RabbitMQ queues via the management UI (port 15672) to verify event flow.
• Use docker logs -f for quick tailing.
• Distributed tracing with OpenTelemetry Collector exporting to Jaeger or Tempo.

FAQ

What is the recommended way to share TypeScript types between services?

Publish a private npm package (e.g., @myorg/contracts) containing DTOs and interfaces. Each service adds it as a dependency, ensuring compile‑time compatibility.

Can I use a single PostgreSQL instance for multiple services?

Technically yes, but each service should own a separate schema or database to maintain logical isolation. Sharing tables creates hidden coupling.

How do I handle distributed transactions?

Prefer the Saga pattern: orchestrate a series of local transactions with compensating actions. NestJS can coordinate via a state machine or use a library like nestjs-saga.

Is it mandatory to use a message broker?

Not for every interaction. Use synchronous REST/gRPC for low‑latency reads, and async messaging for fire‑and‑forget or eventual consistency scenarios.

How do I version my APIs without breaking clients?

Include version in the URL path (/v1/users) and maintain both versions simultaneously during a deprecation window. Document changes in a changelog.

What monitoring stack works well with this setup?

Prometheus for metrics, Grafana for dashboards, Loki for logs, and Tempo/Jaeger for traces. The OpenTelemetry SDK integrates natively with NestJS.

Can I run the gateway and services on the same host without Docker?

Yes, for development you can start each npm run start:dev on different ports and configure the gateway to point to localhost:port. Docker simply mirrors production networking.

How do I secure service‑to‑service communication?

Use mutual TLS (mTLS) via a service mesh (Istio, Linkerd) or implement a shared secret header validated by a guard in each service.

Conclusion

Building scalable microservices with NestJS and Docker gives you a powerful combination: a structured, type‑safe framework that encourages modular design, and a container platform that guarantees identical environments from laptop to cluster. By following the architecture, code patterns, and operational practices outlined above, you can ship features faster, isolate failures, and scale individual components on demand.

Ready to put this into practice? Clone the starter monorepo from GitHub, run docker compose up, and start extending the services for your own domain. If you found this guide useful, subscribe to the newsletter for more deep‑dives on Node.js architecture and DevOps.