Non-Root Containers

Run Node.js as a non-root user so a container escape or RCE does not grant host-level privileges.

Recipe

Quick-reference recipe card - copy-paste ready.

FROM node:24-bookworm-slim
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
COPY dist ./dist
RUN chown -R node:node /app
 
USER node
ENV NODE_ENV=production
CMD ["node", "dist/main.js"]

When to reach for this: Every production Node image. CIS Docker benchmarks and most K8s policies require non-root UIDs.

Working Example

FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json src ./
RUN npm run build
 
FROM node:24-bookworm-slim AS prod
WORKDIR /app
 
# Install as root, then hand off ownership
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
COPY --from=build /app/dist ./dist
 
# Writable dirs the app needs at runtime
RUN mkdir -p /app/tmp /app/logs \
  && chown -R node:node /app
 
USER node
 
EXPOSE 3000
CMD ["node", "dist/main.js"]

// src/main.ts - bind non-privileged port
import express from "express";
 
const app = express();
const port = Number(process.env.PORT ?? 3000);
 
app.get("/health", (_req, res) => res.json({ status: "ok" }));
 
app.listen(port, "0.0.0.0");

What this demonstrates:

• Official node image includes a node user (UID 1000)
• chown before USER so the app can read node_modules and write logs
• Port 3000 does not require root (only ports below 1024 do)

Deep Dive

How It Works

• Linux containers share the host kernel; root in container is still dangerous (capabilities, socket mounts)
• USER node drops to UID 1000 for the CMD process and children
• Kubernetes securityContext.runAsNonRoot: true rejects images that start as UID 0

Kubernetes Security Context

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
      containers:
        - name: api
          image: my-api:1.2.3
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
          volumeMounts:
            - name: tmp
              mountPath: /app/tmp
      volumes:
        - name: tmp
          emptyDir: {}

readOnlyRootFilesystem requires writable mounts for temp files and Unix sockets.

Custom UID for OpenShift

Some platforms require arbitrary UIDs. Build with group-writable dirs:

RUN chgrp -R 0 /app && chmod -R g=u /app
USER 1001

OpenShift runs as a random UID in the root group; g=u grants write access.

File Permissions Checklist

Gotchas

• USER node before COPY - files owned by root, app cannot write. Fix: chown after all copies.
• Binding port 80 - fails without root. Fix: listen on 3000; ingress maps 443 to 3000.
• npm install as node in build - cache permission errors. Fix: install as root in build stage, chown, then USER node.
• Volume mounts override ownership - host dirs owned by root. Fix: fsGroup in K8s or initContainer chown.
• Prisma/sqlite writing to /app - read-only root FS breaks. Fix: mount emptyDir at /app/data.
• Assuming node user exists on distroless - use nonroot user instead.

Alternatives

FAQs

docker run --rm my-api id
# uid=1000(node) gid=1000(node)

Related

• Docker Basics - first Dockerfile
• Multi-Stage Builds - chown in final stage
• Distroless & Alpine Trade-offs - nonroot user
• Health & Readiness Probes - probes as non-root
• Docker Best Practices - section checklist

External Related Links

• NodeSource Blog & Resources - Enterprise Node.js performance and security content.
• Node.js Best Practices (GitHub) - Curated production best practices.
• DigitalOcean Node.js Tutorials - Production-oriented how-tos.
• Distributed Systems with Node.js - Enterprise-ready distributed systems.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Y29kZWd1aWRlcy5pb3xjZ2lvODAzfDIwMjYwNw==