mirror of
https://github.com/vercel/next.js.git
synced 2026-09-20 02:25:18 +08:00
Kristiyan Velkov
d7732c57d6
## What? Modernizes the existing `with-docker` example and adds a new `with-docker-export-output` example demonstrating different Next.js deployment strategies with Docker best practices: 1. **`with-docker` (updated)** - Modernized to use App Router, TypeScript, Tailwind CSS v4, and comprehensive Docker best practices. Now includes both Node.js and Bun Dockerfile options, Docker Compose with profiles, BuildKit cache mounts, and extensive documentation. 2. **`with-docker-export-output` (new)** - Demonstrates Next.js static export mode deployment with Docker, offering two serving options: **Nginx** (production-grade) and **serve** package (Node.js-based, simpler setup). Includes optimized Nginx configuration, BuildKit cache mounts, and comprehensive documentation. Both examples include detailed documentation explaining Docker best practices, implementation decisions, and deployment guidance. ## Why? The existing `with-docker` example was using the Pages Router and lacked: - Modern Next.js patterns (App Router, TypeScript) - Detailed documentation explaining Docker best practices and implementation decisions - BuildKit cache mounts for optimized build performance - Bun runtime support as an alternative to Node.js - Docker Compose configurations for easier local development - Clear documentation about Node.js image variant choices (slim vs Alpine) - Examples demonstrating static export mode These updates serve as comprehensive references for developers who want to understand: - How to Dockerize Next.js applications for different deployment scenarios - Why certain choices are made and how to optimize Docker setups for production - When to use standalone mode vs static export mode - How to choose between Node.js and Bun runtimes - How to choose between different web servers (Nginx vs serve) for static sites ## How? ### `with-docker` example (updated) - **Migrated to App Router** with TypeScript and Tailwind CSS v4 - **Multi-stage Dockerfile** with three stages: dependencies installation, build, and runtime - **Bun support** via `Dockerfile.bun` with optimized configuration - **BuildKit cache mounts** for package manager stores (`npm`, `yarn`, `pnpm`, `bun`) and Next.js build cache - **Security best practices** with non-root user execution (built-in `node` and `bun` users) - **Docker Compose configuration** with profiles for Node.js (default) and Bun - **Comprehensive `.dockerignore`** to minimize build context size - **Detailed README** explaining standalone mode benefits, Node.js image choices, and deployment guidance - **Deleted** `with-docker-standalone-output` (merged into this example) ### `with-docker-export-output` example (new) - **Two Dockerfile options:** - `Dockerfile` - Nginx-based serving with `nginxinc/nginx-unprivileged` for security - `Dockerfile.serve` - Node.js serve package-based serving for simpler deployments - **Multi-stage builds** for both options with separate dependency, build, and runtime stages - **BuildKit cache mounts** for package manager stores and Next.js build cache - **Production Nginx configuration** (`nginx.conf`) with gzip compression, caching headers, and security best practices - **Docker Compose configuration** supporting both serving options via profiles - **Comprehensive README** explaining static export mode, trade-offs between Nginx and serve ### Docker best practices implemented (both examples) | Practice | Description | |----------|-------------| | Multi-stage builds | Optimal image size reduction | | Layer caching | Package files copied first | | Minimal build context | Comprehensive `.dockerignore` files | | BuildKit cache mounts | Faster subsequent builds | | Security hardening | Non-root user execution | | Corepack | yarn/pnpm version management | | Package manager auto-detection | npm, yarn, pnpm support | | Node.js 24.13.0-slim | Clear upgrade guidance | ## Breaking Changes > **Warning** > - `with-docker` now uses App Router instead of Pages Router > - `with-docker-standalone-output` has been removed (merged into `with-docker`) --- **Note:** After this PR is approved and merged, I plan to open a follow-up PR to update the Next.js documentation with proper links to these Docker examples. --------- Co-authored-by: Wyatt Johnson <accounts+github@wyattjoh.ca> Co-authored-by: Joseph <joseph.chamochumbi@vercel.com> Co-authored-by: kristiyan.velkov <kristiyan.velkov@ffw.com>
97 lines
3.2 KiB
Docker
97 lines
3.2 KiB
Docker
# ============================================
|
|
# Stage 1: Dependencies Installation Stage
|
|
# ============================================
|
|
|
|
# IMPORTANT: Node.js and Nginxinc Image Version Maintenance
|
|
# This Dockerfile uses Node.js 24.13.0-slim and Nginxinc image with alpine3.22, which was the latest LTS version at the time of writing.
|
|
# To ensure security and compatibility, regularly validate and update the NODE_VERSION ARG and NGINXINC_IMAGE_TAG to the latest LTS versions.
|
|
|
|
ARG NODE_VERSION=24.13.0-slim
|
|
ARG NGINXINC_IMAGE_TAG=alpine3.22
|
|
|
|
FROM node:${NODE_VERSION} AS dependencies
|
|
|
|
# Set the working directory
|
|
WORKDIR /app
|
|
|
|
# Copy package-related files first to leverage Docker's caching mechanism
|
|
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
|
|
|
|
# Install project dependencies with frozen lockfile for reproducible builds
|
|
RUN --mount=type=cache,target=/root/.npm \
|
|
--mount=type=cache,target=/usr/local/share/.cache/yarn \
|
|
--mount=type=cache,target=/root/.local/share/pnpm/store \
|
|
if [ -f package-lock.json ]; then \
|
|
npm ci --no-audit --no-fund; \
|
|
elif [ -f yarn.lock ]; then \
|
|
corepack enable yarn && yarn install --frozen-lockfile --production=false; \
|
|
elif [ -f pnpm-lock.yaml ]; then \
|
|
corepack enable pnpm && pnpm install --frozen-lockfile; \
|
|
else \
|
|
echo "No lockfile found." && exit 1; \
|
|
fi
|
|
|
|
# ============================================
|
|
# Stage 2: Build Next.js Application
|
|
# ============================================
|
|
|
|
FROM node:${NODE_VERSION} AS builder
|
|
|
|
# Set the working directory
|
|
WORKDIR /app
|
|
|
|
# Copy project dependencies from dependencies stage
|
|
COPY --from=dependencies /app/node_modules ./node_modules
|
|
|
|
# Copy application source code
|
|
COPY . .
|
|
|
|
ENV NODE_ENV=production
|
|
|
|
# Next.js collects completely anonymous telemetry data about general usage.
|
|
# Learn more here: https://nextjs.org/telemetry
|
|
# Uncomment the following line in case you want to disable telemetry during the build.
|
|
# ENV NEXT_TELEMETRY_DISABLED=1
|
|
|
|
# Build Next.js application
|
|
RUN --mount=type=cache,target=/app/.next/cache \
|
|
if [ -f package-lock.json ]; then \
|
|
npm run build; \
|
|
elif [ -f yarn.lock ]; then \
|
|
corepack enable yarn && yarn build; \
|
|
elif [ -f pnpm-lock.yaml ]; then \
|
|
corepack enable pnpm && pnpm build; \
|
|
else \
|
|
echo "No lockfile found." && exit 1; \
|
|
fi
|
|
|
|
# =========================================
|
|
# Stage 3: Serve Static Files with Nginx
|
|
# =========================================
|
|
|
|
FROM nginxinc/nginx-unprivileged:${NGINXINC_IMAGE_TAG} AS runner
|
|
|
|
# Set the working directory
|
|
WORKDIR /app
|
|
|
|
# Next.js collects completely anonymous telemetry data about general usage.
|
|
# Learn more here: https://nextjs.org/telemetry
|
|
# Uncomment the following line in case you want to disable telemetry during the run time.
|
|
# ENV NEXT_TELEMETRY_DISABLED=1
|
|
|
|
# Copy custom Nginx config
|
|
COPY nginx.conf /etc/nginx/nginx.conf
|
|
|
|
# Copy the static build output from the build stage to Nginx's default HTML serving directory
|
|
COPY --from=builder /app/out /usr/share/nginx/html
|
|
|
|
# Non-root user for security best practices
|
|
USER nginx
|
|
|
|
# Expose port 8080 to allow HTTP traffic
|
|
EXPOSE 8080
|
|
|
|
# Start Nginx directly with custom config
|
|
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
|
|
CMD ["-g", "daemon off;"]
|