Deploying Node.js Microservices

Fastify vs Express

• Fastify: ~77k req/s, schema validation, built-in logging
• Express: ~15k req/s, massive ecosystem, simpler mental model
• Both work — Fastify is preferred for high-throughput microservices

Monorepo (Recommended for Most Teams)

platform/
├── packages/
│   ├── shared-types/        # Shared TS interfaces
│   ├── logger/              # Shared pino config
│   └── auth-middleware/     # JWT validation
├── services/
│   ├── user-service/
│   │   ├── src/
│   │   │   ├── server.ts
│   │   │   ├── config.ts
│   │   │   ├── routes/
│   │   │   ├── services/
│   │   │   └── repositories/
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── order-service/
│   └── payment-service/
├── docker-compose.yml
├── turbo.json               # Turborepo config
└── package.json             # Workspace root

/health (Liveness)

• Returns 200 if process is alive
• K8s restarts container if this fails
• Keep it fast — no DB calls

Why It Matters

• K8s sends SIGTERM before killing a pod
• Default grace period: 30 seconds
• Without handling: dropped requests, corrupt data

12-Factor App Config

• Store config in environment variables
• Never commit secrets to source control
• Same artefact deployed to all environments
• Only env vars change between dev/staging/prod

Multi-Stage Benefits

• Final image has no devDependencies
• No TypeScript compiler in production
• Image size: ~150 MB (Alpine) vs ~900 MB (full)

Publisher (order-service)

// src/mq.ts — RabbitMQ with amqplib
import amqp from 'amqplib';

let connection: amqp.Connection;
let channel: amqp.Channel;

export async function connectMQ(url: string) {
  connection = await amqp.connect(url);
  channel = await connection.createChannel();

  // Ensure exchange exists
  await channel.assertExchange(
    'events', 'topic', { durable: true }
  );
  return { connection, channel };
}

// Publish a domain event
export async function publishEvent(
  routingKey: string,
  payload: Record<string, unknown>
) {
  const msg = JSON.stringify({
    id: crypto.randomUUID(),
    type: routingKey,
    timestamp: new Date().toISOString(),
    data: payload,
  });

  channel.publish(
    'events',
    routingKey,
    Buffer.from(msg),
    { persistent: true, contentType: 'application/json' }
  );
}

Simple Express Gateway

// gateway/src/server.ts
import express from 'express';
import { createProxyMiddleware } from
  'http-proxy-middleware';
import rateLimit from 'express-rate-limit';
import { verifyJWT } from './auth.js';

const app = express();

// Global rate limiting
app.use(rateLimit({
  windowMs: 60_000,
  max: 100,
  standardHeaders: true,
}));

// Auth middleware (skip for public routes)
app.use('/api', verifyJWT);

// Route to services
app.use('/api/users',
  createProxyMiddleware({
    target: 'http://user-service:3000',
    pathRewrite: { '^/api/users': '/api/users' },
    changeOrigin: true,
  })
);

app.use('/api/orders',
  createProxyMiddleware({
    target: 'http://order-service:3001',
    pathRewrite: { '^/api/orders': '/api/orders' },
    changeOrigin: true,
  })
);

app.use('/api/payments',
  createProxyMiddleware({
    target: 'http://payment-service:3002',
    pathRewrite: {
      '^/api/payments': '/api/payments'
    },
    changeOrigin: true,
  })
);

app.listen(8080, () =>
  console.log('Gateway on :8080')
);

JWT Middleware

// src/middleware/auth.ts
import jwt from 'jsonwebtoken';
import { config } from '../config.js';
import { FastifyRequest, FastifyReply } from 'fastify';

interface JWTPayload {
  sub: string;
  email: string;
  roles: string[];
  iat: number;
  exp: number;
}

export async function verifyJWT(
  req: FastifyRequest,
  reply: FastifyReply
) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return reply.status(401).send({
      error: 'Missing bearer token'
    });
  }

  try {
    const token = header.slice(7);
    const payload = jwt.verify(
      token, config.JWT_SECRET
    ) as JWTPayload;

    // Attach to request for downstream use
    req.user = payload;
  } catch (err) {
    return reply.status(401).send({
      error: 'Invalid or expired token'
    });
  }
}

// Propagate JWT to downstream services
export function forwardAuth(req: FastifyRequest) {
  return {
    Authorization: req.headers.authorization,
    'X-Request-Id': req.headers['x-request-id'],
  };
}

Structured Logging with Pino

// src/logger.ts
import pino from 'pino';
import { config } from './config.js';

export const logger = pino({
  level: config.LOG_LEVEL,
  base: {
    service: 'order-service',
    version: process.env.npm_package_version,
    env: config.NODE_ENV,
  },
  timestamp: pino.stdTimeFunctions.isoTime,
  formatters: {
    level: (label) => ({ level: label }),
  },
  redact: ['req.headers.authorization',
           'req.headers.cookie'],
});

ECS Task Definition

{
  "family": "user-service",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions": [{
    "name": "user-service",
    "image": "123456789.dkr.ecr.us-east-1.amazonaws.com/user-service:1.4.2",
    "portMappings": [{ "containerPort": 3000 }],
    "environment": [
      { "name": "NODE_ENV", "value": "production" }
    ],
    "secrets": [{
      "name": "DATABASE_URL",
      "valueFrom": "arn:aws:ssm:us-east-1:123456789:parameter/prod/user-service/db-url"
    }],
    "healthCheck": {
      "command": ["CMD-SHELL",
        "wget -qO- http://localhost:3000/health || exit 1"],
      "interval": 30,
      "timeout": 5,
      "retries": 3
    },
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "/ecs/user-service",
        "awslogs-region": "us-east-1",
        "awslogs-stream-prefix": "ecs"
      }
    }
  }]
}

Why Own Your Data

• Independent schema evolution
• Choose the right DB per workload
• No shared-DB coupling between teams
• Services can be deployed independently

Circuit Breaker (opossum)

import CircuitBreaker from 'opossum';

const breaker = new CircuitBreaker(
  async (userId: string) => {
    const res = await fetch(
      `${config.USER_SERVICE_URL}/api/users/${userId}`
    );
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  },
  {
    timeout: 3000,           // 3s per call
    errorThresholdPercentage: 50,
    resetTimeout: 10000,     // try again after 10s
    volumeThreshold: 5,      // min calls before tripping
  }
);

breaker.on('open',    () => log.warn('Circuit OPEN'));
breaker.on('halfOpen',() => log.info('Circuit HALF-OPEN'));
breaker.on('close',   () => log.info('Circuit CLOSED'));

// Usage
breaker.fallback(() => ({ id: userId, name: 'Unknown' }));
const user = await breaker.fire(userId);

Key Takeaways

1. Start monolithic — extract services when team/scaling pain is real
2. Each service: health checks, graceful shutdown, structured logging
3. Validate config at startup — fail fast, not at 3 AM
4. Multi-stage Dockerfiles, non-root user, Alpine base
5. Prefer async messaging over sync HTTP between services
6. Database per service + saga pattern for consistency
7. Circuit breakers, retries, timeouts on every call
8. Correlation IDs in every log line across every service