Agent-Skills.md

Agent Skills: Deployment & Ops Standards

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. (triggers: Dockerfile, k8s/**, helm/**, max-old-space-size, shutdown hooks)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nestjs-deployment

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nestjs/nestjs-deployment

Skill Files

Browse the full folder contents for nestjs-deployment.

Download Skill

Loading file tree…

skills/nestjs/nestjs-deployment/SKILL.md

Skill Metadata

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. (triggers: Dockerfile, k8s/**, helm/**, max-old-space-size, shutdown hooks)"

Deployment & Ops Standards

Priority: P1 (OPERATIONAL)

Docker optimization and production deployment standards for NestJS applications.

Workflow: Containerize a 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 the 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 a 5-10s sleep pre-stop hook for LB draining.

Dockerfile Example

See implementation examples

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.

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 is a security risk.
  • No unbounded Node heap: Set --max-old-space-size to ~75% of container memory limit.