# NestJS Production Stack

> Production NestJS with Bull queues, PostgreSQL, and Redis.

- Category: Full Web Stacks
- Difficulty: advanced
- Components: nestjs, bull, postgresql, redis, nginx
- Tags: nestjs, nodejs, typescript, bull, production
- Source: https://docker.recipes/full-stacks/nestjs-production

## Overview

NestJS is a progressive Node.js framework built with TypeScript that uses decorators and modules to create scalable server-side applications. Inspired by Angular's architecture, NestJS brings enterprise-grade structure to Node.js development with built-in support for dependency injection, guards, interceptors, and pipes. It has gained significant traction since 2017 for building maintainable APIs and microservices that can scale with growing applications.

This production stack combines NestJS with Bull queues for background job processing, PostgreSQL for robust data persistence, and Redis for caching and session management. Bull leverages Redis to manage job queues with features like job retries, delayed processing, and priority queuing, while PostgreSQL provides ACID-compliant data storage with advanced querying capabilities. The NGINX reverse proxy handles load balancing, SSL termination, and static file serving to optimize performance under production loads.

Development teams building SaaS platforms, e-commerce applications, or content management systems will benefit from this stack's enterprise-ready architecture. The combination addresses common production challenges like background processing for email notifications, image resizing, or data exports, while maintaining data integrity through PostgreSQL's transaction support. TypeScript throughout the stack ensures type safety and reduces runtime errors in production environments.

## Features

- Bull queue management with Redis backend for reliable background job processing and retry mechanisms
- TypeORM integration with PostgreSQL for type-safe database operations and migration management
- NestJS modular architecture with dependency injection and decorator-based routing
- Redis-based session storage and caching layer for improved application performance
- Bull Board dashboard for monitoring queue status, failed jobs, and processing metrics
- NGINX reverse proxy with load balancing and SSL termination capabilities
- JWT authentication infrastructure built into the NestJS application
- PostgreSQL JSONB support for flexible document storage alongside relational data

## Use cases

- SaaS applications requiring background processing for user-generated content, email campaigns, or data exports
- E-commerce platforms handling order processing, inventory updates, and payment notifications through queues
- Content management systems with image resizing, video transcoding, and search indexing workflows
- Financial applications needing ACID-compliant transactions and audit logging with PostgreSQL
- Multi-tenant applications leveraging PostgreSQL's row-level security and NestJS guards
- API-first applications serving mobile apps and SPAs with JWT authentication and Redis session management
- Data analytics platforms processing large datasets through Bull queues with PostgreSQL aggregation

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration
- Minimum 2GB RAM recommended (PostgreSQL: 1GB+, Redis: 512MB+, NestJS: 256MB+, NGINX: 256MB+)
- Available ports 80, 443 (NGINX), and 3001 (Bull Board) on the host system
- Environment variables: POSTGRES_PASSWORD and JWT_SECRET must be configured
- Basic understanding of TypeScript, decorators, and NestJS module system
- SSL certificates for production NGINX configuration with HTTPS termination

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=nestjs
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=nestjs_app
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - nestjs_net

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - nestjs_net

  nestjs:
    build:
      context: .
      dockerfile: Dockerfile
    command: node dist/main.js
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://nestjs:${POSTGRES_PASSWORD}@postgres:5432/nestjs_app
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=${JWT_SECRET}
    depends_on:
      - postgres
      - redis
    networks:
      - nestjs_net

  bull-board:
    image: deadly0/bull-board:latest
    ports:
      - "3001:3000"
    environment:
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - redis
    networks:
      - nestjs_net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - nestjs
    networks:
      - nestjs_net

volumes:
  postgres_data:
  redis_data:

networks:
  nestjs_net:
```

## .env

```bash
# NestJS Production
POSTGRES_PASSWORD=secure_postgres_password
JWT_SECRET=your_jwt_secret_key_here

# NestJS at http://localhost
# Bull Board at http://localhost:3001
```

## Usage notes

- NestJS at http://localhost
- Bull Board at http://localhost:3001
- TypeORM for PostgreSQL
- Bull queues with Redis
- JWT authentication ready

## Troubleshooting

- NestJS container fails to connect to PostgreSQL: Ensure POSTGRES_PASSWORD environment variable matches in both services and verify the DATABASE_URL format
- Bull queues not processing jobs: Check Redis connectivity and ensure REDIS_HOST points to the redis service name, not localhost
- TypeORM migration errors: Run migrations manually with 'docker-compose exec nestjs npm run migration:run' if auto-migration fails
- Bull Board shows empty queues: Verify Redis connection parameters match between NestJS Bull configuration and Bull Board environment variables
- NGINX returns 502 Bad Gateway: Check that NestJS service is healthy and listening on the correct internal port, usually 3000
- PostgreSQL container exits with permission errors: Ensure the postgres_data volume has correct ownership or recreate the volume

