mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
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 <[email protected]> Co-authored-by: Joseph <[email protected]> Co-authored-by: kristiyan.velkov <[email protected]>
98 lines
3.1 KiB
Docker
98 lines
3.1 KiB
Docker
# =========================================
|
|
# Stage 1: Install Dependencies
|
|
# =========================================
|
|
|
|
# IMPORTANT: Node.js Version Maintenance
|
|
# This Dockerfile uses Node.js 24.13.0-slim, which was the latest LTS version at the time of writing.
|
|
# To ensure security and compatibility, regularly update the NODE_VERSION ARG to the latest LTS version.
|
|
ARG NODE_VERSION=24.13.0-slim
|
|
|
|
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 package-lock.json* yarn.lock* pnpm-lock.yaml* ./
|
|
|
|
# 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
|
|
# Cache mount speeds up subsequent builds by persisting Next.js build cache
|
|
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 serve
|
|
# =========================================
|
|
|
|
FROM node:${NODE_VERSION} AS runner
|
|
|
|
# Set the working directory
|
|
WORKDIR /app
|
|
|
|
# Install serve globally (pinned version for reproducibility, update to the latest version as needed)
|
|
# Cache npm global installs to speed up builds
|
|
RUN --mount=type=cache,target=/root/.npm \
|
|
npm install -g [email protected]
|
|
|
|
# Set the port for serve (default is 3000)
|
|
ENV PORT=3000
|
|
|
|
# Copy the static build output from the build stage
|
|
COPY --from=builder --chown=node:node /app/out ./out
|
|
|
|
# Use the built-in non-root user for security best practices
|
|
USER node
|
|
|
|
# Expose port 3000 to allow HTTP traffic
|
|
EXPOSE 3000
|
|
|
|
# Start serve to serve static files
|
|
# -s: serve single-page application (SPA) mode
|
|
# -l: listen on specified port
|
|
# -n: no clipper (don't show file listing)
|
|
CMD ["serve", "-s", "out", "-l", "3000", "-n"]
|