Build it

Take a NestJS API, make it stateless, run three copies behind Nginx, and make its nightly job run once. You can practise the capacity math from step 8 in your browser, in the Practice section below.

1. Audit the app with a stateless checklist

   Paste this into the repo as a pull request template section, and answer each line before you scale out.

   MarkdownCopy

   ## Stateless check (must be all "yes" before running 2+ copies)
   - [ ] Sessions live in Redis, or we use signed tokens. No MemoryStore.
   - [ ] No file is written to local disk except temp files deleted in the same request.
   - [ ] Uploads go to object storage (S3 / R2 / MinIO). We store only the key.
   - [ ] Any in-memory cache is OK to be different per copy, or it lives in Redis.
   - [ ] No @Cron / setInterval does business work inside the API process.
   - [ ] Rate-limit counters and locks live in Redis.
   - [ ] All config comes from environment variables. Same image in staging and prod.
   - [ ] The app handles SIGTERM: enableShutdownHooks(), finishes in-flight requests.
   - [ ] GET /health answers in under 50 ms and does not need a logged-in user.

2. Add a health endpoint and a "served by" header

   The health endpoint lets Docker and the load balancer ask "are you alive?". The header shows which copy answered, so you can watch requests spread. The Load balancers lesson upgrades this check to ping the database.

   TypeScriptCopy

   // health.controller.ts
   import { Controller, Get } from '@nestjs/common';
   import { hostname } from 'node:os';
   
   @Controller('health')
   export class HealthController {
     @Get()
     check() {
       // Cheap on purpose: no DB call, no auth
       return { status: 'ok', instance: hostname(), uptimeS: Math.round(process.uptime()) };
     }
   }
   
   // main.ts
   import { NestFactory } from '@nestjs/core';
   import { hostname } from 'node:os';
   import type { Request, Response, NextFunction } from 'express';
   import { AppModule } from './app.module';
   
   async function bootstrap() {
     const app = await NestFactory.create(AppModule);
     app.enableShutdownHooks(); // close Prisma/Redis cleanly on SIGTERM
     app.use((req: Request, res: Response, next: NextFunction) => {
       res.setHeader('X-Served-By', hostname()); // in Docker: the container id
       next();
     });
     await app.listen(3000);
   }
   bootstrap();

3. Write a Compose file that allows many copies

   Two things block scaling in Compose: a fixed container_name and a host port mapping on the API (three copies cannot all bind host port 3000). Only Nginx publishes a port.

   YAMLCopy

   # docker-compose.yml
   services:
     api:
       build: .
       # no container_name and no ports: so Compose can run several copies
       environment:
         DATABASE_URL: postgresql://app:app@db:5432/shop?connection_limit=5
         REDIS_URL: redis://redis:6379
       healthcheck:
         test: ["CMD", "node", "-e", "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
         interval: 10s
         timeout: 3s
         retries: 3
       depends_on: [db, redis]
     nginx:
       image: nginx:1.27-alpine
       ports: ["8080:80"]
       volumes:
         - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
       depends_on:
         api:
           condition: service_healthy
     redis:
       image: redis:7-alpine
     db:
       image: postgres:16
       environment:
         POSTGRES_USER: app
         POSTGRES_PASSWORD: app
         POSTGRES_DB: shop

4. Point Nginx at the service name

   Inside Compose, the name api resolves to one IP address per running copy. When an upstream server name resolves to several addresses, Nginx uses all of them and rotates between them.

   nginxCopy

   # nginx.conf
   upstream api_pool {
       server api:3000;        # resolved once at startup: one entry per copy
       keepalive 32;           # reuse connections to the copies
   }
   
   server {
       listen 80;
   
       location / {
           proxy_pass http://api_pool;
           proxy_http_version 1.1;
           proxy_set_header Connection "";          # needed for keepalive
           proxy_set_header Host $host;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       }
   }

5. Scale to three and watch the requests spread

   Nginx resolves api only when it starts or reloads, so reload it after you change the number of copies.

   TerminalCopy

   docker compose up -d --build --scale api=3
   docker compose exec nginx nginx -s reload     # pick up the new copies
   
   for i in 1 2 3 4 5 6; do
     curl -s -o /dev/null -D - http://localhost:8080/health | grep -i x-served-by
   done

   OutputCopy

   X-Served-By: 3f2a9c1d0b7e
   X-Served-By: 91c4e07aa2d3
   X-Served-By: c0d81b5f6e42
   X-Served-By: 3f2a9c1d0b7e
   X-Served-By: 91c4e07aa2d3
   X-Served-By: c0d81b5f6e42

   Now stop one copy with docker stop and run the loop again. The first request that Nginx sends to the dead copy may be slow or fail. Then Nginx marks that copy as failed for a while and the other two keep answering. The Load balancers lesson tunes how fast that happens.

6. Move sessions to Redis

   A small session service with ioredis. The cookie holds only a random id; the data lives in Redis with an expiry, so every copy sees the same login.

   TypeScriptCopy

   // session.service.ts
   import { Inject, Injectable } from '@nestjs/common';
   import { randomBytes } from 'node:crypto';
   import type Redis from 'ioredis';
   
   export interface SessionData { userId: number; siteIds: number[] }
   const TTL_S = 8 * 60 * 60; // one store shift
   
   @Injectable()
   export class SessionService {
     // provider: { provide: 'REDIS', useFactory: () => new Redis(process.env.REDIS_URL!) }
     constructor(@Inject('REDIS') private readonly redis: Redis) {}
   
     async create(data: SessionData): Promise<string> {
       const sid = randomBytes(32).toString('base64url'); // unguessable id for the cookie
       await this.redis.set(`sess:${sid}`, JSON.stringify(data), 'EX', TTL_S);
       return sid;
     }
   
     async get(sid: string): Promise<SessionData | null> {
       const raw = await this.redis.get(`sess:${sid}`);
       return raw ? (JSON.parse(raw) as SessionData) : null;
     }
   
     async destroy(sid: string): Promise<void> {
       await this.redis.del(`sess:${sid}`); // logout works on every copy at once
     }
   }

7. Make the nightly job run once

   Replace the in-process cron with a BullMQ job scheduler. The schedule is stored in Redis under a fixed id, so when all three copies call upsertJobScheduler on startup there is still one schedule. Each run becomes one job, and only one worker takes it. upsertJobScheduler needs BullMQ 5.16 or later; older versions use queue.add with a repeat option. The Queues and background jobs lesson covers queues fully.

   Before (runs 3 times)After (runs once)

   TypeScriptCopy

   import { Injectable } from '@nestjs/common';
   import { Cron } from '@nestjs/schedule';
   
   @Injectable()
   export class StockReportCron {
     // Every copy of the API has this timer, so 3 copies = 3 runs
     @Cron('0 2 * * *', { timeZone: 'Asia/Jakarta' })   // the stores' time zone
     async nightly() {
       await this.buildLowStockReportAndSendSms();
     }
   
     private async buildLowStockReportAndSendSms() { /* ... */ }
   }

8. Do the capacity math

   Load-test one copy in staging (for example npx autocannon -c 50 -d 30 http://staging:8080/articles/1001) and find the highest request rate where p95 still meets your target. Then write the plan down where the team can see it.

   OutputCopy

   Peak QPS (from your estimate)               400 req/s
   One copy at p95 < 300 ms (load test)        150 req/s
   Keep each copy at ~70%                      150 x 0.7 = 105 req/s
   Copies for the peak                         400 / 105 = 3.8  -> 4
   Plus one spare (crash or deploy)            5 copies
   DB connections                              5 x connection_limit 5 = 25
   Postgres max_connections                    100  -> fine, room for workers