Nestjs DeploymentSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nestjs-deployment
description: Containerize NestJS apps with multi-stage Docker builds, tune Node.js memory, and implement graceful shutdown hooks. Use when writing Dockerfiles, configuring K8s deployments, or adding shutdown hooks for NestJS.
metadata:
  triggers:
    files:
    - 'k8s/**'
    - 'helm/**'
    keywords:
    - Dockerfile
    - max-old-space-size
    - shutdown hooks
---
# Deployment & Ops Standards

## **Priority: P1 (HIGH)**


## Workflow: Containerize NestJS App

1. **Write multi-stage Dockerfile** — Build stage installs devDeps and runs `nest build`; run stage copies only `dist` and pruned `node_modules`.
2. **Set non-root user** — Add `USER node` to Dockerfile.
3. **Tune memory** — Set `--max-old-space-size` to ~75% of container memory limit.
4. **Enable shutdown hooks** — Call `app.enableShutdownHooks()` in `main.ts`.
5. **Add K8s pre-stop** — Configure 5-10s sleep pre-stop hook for LB draining.

## Dockerfile Example

See [implementation examples](references/example.md)

## 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()` mandatory.
 - **Sleep**: Add "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 **Init Container** in Kubernetes that runs `npm run typeorm:migration:run` before app container starts.

## Environment Variables & CI/CD

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


## Anti-Patterns

- **No migrations in main.ts**: Use K8s Init Containers or pre-deploy CI steps for migration runs.
- **No root user in Docker**: Always add `USER node` to Dockerfile; running as root security risk.
- **No unbounded Node heap**: Set `--max-old-space-size` to ~75% of container memory limit.

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.