Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Testing and Deployment

Deploying Fastify: Docker, Environments, Shutdown

Ship a Fastify app: listen on 0.0.0.0, configure through environment variables, build a small Docker image, add health checks and shut down gracefully on SIGTERM.

A Fastify app that works on your laptop needs a few extra habits to survive in production: it must listen on the right address, read configuration from the environment, expose a health endpoint, run in a container or under a process manager, and stop politely when the platform restarts it. This lesson goes through those steps in order.

Fastify and Docker are not available on this site's runner, so the Docker and Fastify snippets are read-only. The graceful-shutdown mechanics are demonstrated with plain node:http, which is exactly what Fastify uses underneath.

Production checklist

Listen on 0.0.0.0 Containers need it.
Env config Port, secrets, log level.
Health checks Let the platform probe you.
Graceful stop Finish work on SIGTERM.

Most outages at deploy time are shutdown bugs.

1 / 2

Listen on the right address

By default, Fastify's listen({ port: 3000 }) binds to 127.0.0.1, which only accepts connections from the same machine. Inside a Docker container that means nothing outside can reach you. Bind to all interfaces:

JavaScript
// src/server.js (real Fastify)
import { buildApp } from './app.js';

const app = buildApp({
  logger: { level: process.env.LOG_LEVEL ?? 'info' },
  trustProxy: true,                       // behind nginx, a load balancer or a CDN
});

try {
  await app.listen({ port: Number(process.env.PORT ?? 3000), host: '0.0.0.0' });
} catch (err) {
  app.log.error(err);
  process.exit(1);
}

trustProxy makes request.ip and request.protocol come from X-Forwarded-* headers. Set it only when a proxy you control sits in front; otherwise clients can fake their address.

Configuration through the environment

The twelve-factor rule: the same build runs everywhere, and only the environment changes. Read PORT, HOST, LOG_LEVEL, database URLs and secrets from environment variables, validate them at startup (see Authorization, Input Hardening and Secrets), and keep local defaults in a .env file loaded only in development (node --env-file=.env src/server.js works in modern Node).

Use NODE_ENV=production in production. Many libraries skip development-only work when it is set, and Fastify tooling such as pino-pretty should be used in development only.

A health endpoint

Load balancers and orchestrators need a cheap URL to ask "are you alive?" and "can you take traffic?". Two routes are common:

  • Liveness (/healthz): the process is up. If it fails, restart the container.
  • Readiness (/readyz): dependencies (database, cache) are reachable and the app is not shutting down. If it fails, stop sending traffic but do not restart.
JavaScript
app.get('/healthz', { logLevel: 'silent' }, async () => ({ status: 'ok' }));
app.get('/readyz', async (request, reply) => {
  try { await app.db.query('select 1'); return { status: 'ready' }; }
  catch { return reply.code(503).send({ status: 'not ready' }); }
});

Keep probes light, unauthenticated and quiet in the logs.

A small Docker image

A multi-stage build keeps the final image small and runs as a non-root user (read-only example):

DOCKERFILE
FROM node:24-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

FROM node:24-alpine
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY src ./src
COPY package.json ./
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://127.0.0.1:3000/healthz || exit 1
CMD ["node", "src/server.js"]

Notes: copy package*.json first so the dependency layer is cached; run node directly (not npm start) so signals reach your process; add a .dockerignore with node_modules, .git and .env so secrets never enter the image.

Graceful shutdown

When you deploy, scale down or restart, the platform sends SIGTERM, waits a grace period (Kubernetes: 30 seconds by default), then sends SIGKILL. If your process exits instantly, requests that are in the middle of running get cut off. A graceful shutdown:

  1. Stops accepting new connections.
  2. Lets in-flight requests finish (up to a timeout).
  3. Closes resources (database pools, queues).
  4. Exits with code 0.

In Fastify, app.close() does steps 1 to 3: it stops the server, runs onClose hooks (see Application Hooks: onReady, onClose, onRoute) and resolves when done. You wire it to the signals:

JavaScript
for (const signal of ['SIGTERM', 'SIGINT']) {
  process.on(signal, async () => {
    app.log.info({ signal }, 'shutting down');
    await app.close();
    process.exit(0);
  });
}

The following example shows the mechanics on a plain Node server: a slow request is in flight when shutdown begins, and the server finishes it before closing, while a new request after shutdown starts is refused. A draining flag also makes /readyz answer 503 so a load balancer stops sending traffic first.

Node.js In-flight requests finish, new ones are refused

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

If some clients hold keep-alive connections open, server.close() waits for them. Fastify's forceCloseConnections option (default 'idle' on modern versions) closes idle ones automatically and you can set it to true to cut every connection after the grace period.

Also add a hard timeout: if shutdown takes longer than the platform's grace period, exit anyway with a non-zero code, so a stuck request cannot block deploys forever.

Using all CPU cores

One Node process uses one core for JavaScript. Options, from simplest:

  • Several containers behind a load balancer (the container orchestrator scales for you). Best default.
  • A process manager such as PM2 in cluster mode on a single server.
  • The node:cluster module, where a primary process forks workers that share the port. Remember that in-memory state (caches, rate-limit counters, sessions) is then per worker; move shared state to Redis.

Zero-downtime deploys

Rolling updates work because of everything above: new instances start and pass /readyz, the load balancer shifts traffic, old instances get SIGTERM, drain and exit. Database migrations must be backward compatible with the old code during the overlap: add columns first, deploy code, remove old columns in a later release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must a Fastify app in Docker listen on host 0.0.0.0?

    Binding to the loopback address makes the port unreachable from outside the container.
  2. 2. What does a graceful shutdown do on SIGTERM?

    That sequence prevents cut-off requests during deploys. In Fastify, app.close() performs the closing steps.
  3. 3. What is the difference between liveness and readiness probes?

    Liveness detects a broken process. Readiness detects a process that is fine but cannot serve right now, such as during startup or draining.
  4. 4. Why run node directly in the Dockerfile CMD instead of npm start?

    npm can sit between Docker and your app and swallow signals. Running node as the main process avoids that.

Summary

  • Bind to 0.0.0.0, read config from environment variables, set NODE_ENV=production, and use trustProxy only behind a proxy you control.
  • Expose cheap liveness and readiness endpoints.
  • Build a small multi-stage Docker image, run as a non-root user, run node directly, and keep secrets out of the image.
  • On SIGTERM: go unready, stop accepting connections, finish in-flight work, close resources, exit; add a hard timeout.
  • Scale across cores with several containers or processes and keep shared state outside memory.

Next: Project: Notes API