Add example for Debian without npm or Yarn

[MikeMcC399]

• Addresses: Add Debian-based example to BestPractices for removing npm & Yarn from Docker image #2453

Description

A Debian example is added to Smaller images without npm/yarn to complement the existing Alpine example.

Motivation and Context

Issue #404 requests an image without npm nor Yarn. This is partially achieved by removing Yarn from all future Node.js Docker images based on the upcoming Node.js 26 release and other higher releases.

The npm package manager npm is part of the official Node.js distribution. If the role of Node.js Docker images is to package exactly what Node.js bundles in its releases, then npm must also be included.

Nevertheless, some users do not want to run their Docker image with a package manager to achieve a lower Docker image size or to harden their image against package manager vulnerabilities.

The Docker and Node.js Best Practices document, in the section Smaller images without npm/yarn, already provides an example for Alpine images, using a multi-stage build. The first stage builds the app with npm, then in a second run-time only Docker build stage, only the app and node directory are copied, without copying any npm or yarn package manager directories.

Testing Details

cd $(mktemp -d)
npm init -y
npm install @vercel/ncc
echo 'console.log("Hello world!")' > index.js

Add "build": "ncc build index.js -o dist" to package.json scripts

cat > Dockerfile2 <<'EOT'
FROM node:24-trixie-slim AS builder
WORKDIR /build-stage
COPY package*.json ./
RUN npm ci
# Copy the files you need
COPY . ./
RUN npm run build

FROM debian:trixie-slim
# Create app directory
WORKDIR /usr/src/app
# Add required binaries
RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \
    && rm -rf /var/lib/apt/lists/* \
    && groupadd --gid 1000 node \
    && useradd --uid 1000 --gid node --shell /bin/bash --create-home node \
    && chown node:node ./
COPY --from=builder /usr/local/bin/node /usr/local/bin/
COPY --from=builder /usr/local/bin/docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
USER node
# Update the following COPY lines based on your codebase
COPY --from=builder /build-stage/node_modules ./node_modules
COPY --from=builder /build-stage/dist ./dist
# Run with dumb-init to not start node with PID=1, since Node.js was not designed to run as PID 1
CMD ["dumb-init", "node", "dist/index.js"]
EOT

docker build -t test-small-image-trixie .
docker run --rm test-small-image-trixie # Outputs "Hello world!"
docker run --rm --entrypoint node test-small-image-trixie --version # Outputs v24.14.1
docker run --rm --entrypoint which test-small-image-trixie node # Outputs /usr/local/bin/node
docker run --rm --entrypoint which test-small-image-trixie npm # No output (npm not installed)
docker run --rm --entrypoint which test-small-image-trixie yarn # No output (Yarn not installed)

Example Output

Hello world!
v24.14.1
/usr/local/bin/node

Image sizes Debian

Image	Size (local)	% reduction
node:24-trixie-slim	328.25 MB	0%
test-small-image-trixie	312.03 MB	3%

Image sizes Alpine (from PR #2410) testing steps

Image	Size (local)	% reduction
node:24-alpine3.23	225.05 MB	0%
test-small-image	215.55 MB	2%

Types of changes

• Documentation
• Version change (Update, remove or add more Node.js versions)
• Variant change (Update, remove or add more variants, or versions of variants)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Other (none of the above)

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING.md document.
• All new and existing tests passed.

[MikeMcC399]

Preview

https://github.com/MikeMcC399/docker-node/blob/add-smaller-images-example-debian/docs/BestPractices.md#smaller-images-without-npmyarn