---
name: NestJS Deployment
description: Docker builds, Memory tuning, and Graceful shutdown.
metadata:
  labels: [nestjs, deployment, docker, k8s]
  triggers:
    files: ['Dockerfile', 'k8s/**', 'helm/**']
    keywords: [Dockerfile, max-old-space-size, shutdown hooks]
---

# Deployment & Ops Standards

## **Priority: P1 (OPERATIONAL)**

Docker optimization and production deployment standards for NestJS applications.

## Docker Optimization

- **Multi-Stage Builds**: Mandatory.
  1. **Build Stage**: Install `devDependencies`, build NestJS (`nest build`).
  2. **Run Stage**: Copy only `dist` and `node_modules` (pruned), use `node:alpine`.
- **Security**: Do not run as `root`.
  - **Dockerfile**: `USER node`.

## Runtime Tuning (Node.js)

- **Memory Config**: Container memory != Node memory.
  - **Rule**: Explicitly set Max Old Space.
  - **Command**: `node --max-old-space-size=XXX dist/main`
  - **Calculation**: Set to ~75-80% of Kubernetes Limit. (Limit: 1GB -> OldSpace: 800MB).
- **Graceful Shutdown**:
  - **Signal**: Listen to `SIGTERM`.
  - **NestJS**: `app.enableShutdownHooks()` is mandatory.
  - **Sleep**: Add a "Pre-Stop" sleep in K8s (5-10s) to allow Load Balancer to drain connections before Node process stops accepting traffic.

## Init Patterns

- **Database Migrations**:
  - **Anti-Pattern**: Running migration in `main.ts` on startup.
  - **Pro Pattern**: Use an **Init Container** in Kubernetes that runs `npm run typeorm:migration:run` before the app container starts.

## Environment Variables & CI/CD

- **CI/CD Pipelines (GitHub, GitLab, Azure, etc.)**:
  - If you modify `src/config/env.validation.ts` to add a new environment variable, you **MUST** map it explicitly in your deployment pipeline/infrastructure-as-code.
  - **Platform Context**:
    - **Cloud Run/ECS**: Variables must be explicitly passed in the service definition.
    - **Kubernetes**: New variables must be added to the `Deployment` manifest or `ConfigMap`/`Secret`.
    - **Lambda/Serverless**: Must be added to `serverless.yml` or provider console.
  - **Fundamental Rule**: Application code configuration changes are "breaking changes" for the infrastructure layer. Never assume environment inheritance.