A comprehensive demonstration of containerizing a modern Next.js application using Docker for both development and production workflows. This project showcases industry best practices for front-end containerization, including standalone and static-export builds, development with live sync, and optimized production delivery.
Part of the official Docker Next.js sample guide.
For full reference, including all Docker files and setup details, switch to the development branch.
- 🔥 Modern Next.js with App Router and TypeScript
- ⚡ Standalone & static export — Node server or static files (Nginx / serve)
- 🎨 Tailwind CSS for utility-first styling
- 🐳 Multi-stage Docker builds for optimized production images
- 🔧 Development & production Docker configurations with Compose Watch
- 🧪 Testing with Vitest and Testing Library
- 📦 Docker Compose for easy orchestration
- ☸️ Kubernetes deployment configuration
- 🔒 Security-focused (non-root user, minimal base images)
- 📋 ESLint for code quality
- 🤖 CI/CD with GitHub Actions (see
.github/workflows)
| Layer | Technologies |
|---|---|
| Framework | Next.js 16 (App Router), React 19, TypeScript |
| Styling | Tailwind CSS v4 |
| Testing | Vitest, React Testing Library |
| Container | Docker, Docker Compose |
| Orchestration | Kubernetes (optional) |
| Web Server | Nginx (static export), Node (standalone) |
- Docker (v20.10+)
- Docker Compose (v2.0+)
- Node.js (v24+) — for local development
- npm or yarn or pnpm — for local development
Clone the repository
git clone https://github.com/kristiyan-velkov/docker-nextjs-sample.git
cd docker-nextjs-sampleDevelopment with Docker Compose
docker compose up nextjs-dev --buildAccess the app at http://localhost:3000
Production (standalone)
docker compose up nextjs-prod-standalone --buildProduction (static export + Nginx)
docker compose up nextjs-export --buildNote: Only one service using port 8080 (nextjs-export, nextjs-prod-static-nginx, or nextjs-prod-static-serve) should run at a time.
Install dependencies
pnpm install
# or: npm install | yarn installStart development server
pnpm devRun tests
pnpm run test:runBuild for production
pnpm build# Build development image
docker build -f Dockerfile.dev -t nextjs-app-dev .
# Run development container
docker run -p 3000:3000 -v $(pwd):/app nextjs-app-dev
# Using Docker Compose (recommended, with watch)
docker compose watch nextjs-dev# Build production image
docker build -t nextjs-sample:latest .
# Run production container
docker run -p 3000:3000 nextjs-sample:latest# Build static export + Nginx
docker build -f Dockerfile.export -t nextjs-export .
docker run -p 8080:8080 nextjs-exportdocker compose --profile tools run --rm nextjs-test
docker compose --profile tools run --rm nextjs-lintDeploy the Next.js standalone app using the provided manifest:
# 1. Build the image (must match manifest)
docker build -t nextjs-sample:latest -f Dockerfile .
# 2. Apply the manifest (requires a running cluster, e.g. Docker Desktop K8s)
kubectl apply -f nextjs-sample-kubernetes.yamlThis creates:
- Deployment (
nextjs-sample) — 1 replica - Service (
nextjs-sample-service) — NodePort 30001
Access: http://localhost:30001 (Docker Desktop) or use minikube service nextjs-sample-service --url for minikube.
Cleanup
kubectl delete -f nextjs-sample-kubernetes.yamlSee README.Docker.md for detailed Kubernetes steps (Docker Desktop, minikube, kind).
├── app/ # Next.js App Router
│ ├── components/home/ # Home page components
│ ├── data/ # Author, resources data
│ ├── layout.tsx
│ ├── page.tsx
│ └── globals.css
├── public/ # Static assets
├── Dockerfile # Next.js standalone (production)
├── Dockerfile.dev # Next.js development
├── Dockerfile.export # Next.js static export → Nginx
├── Dockerfile.nginx # Next.js static export → Nginx (alt)
├── Dockerfile.serve # Next.js static export → Node serve
├── compose.yaml # Docker Compose configuration
├── nginx.conf # Nginx config for static export
├── nextjs-sample-kubernetes.yaml # Kubernetes deployment
├── Taskfile.yml # Task automation
└── README.Docker.md # Docker & Kubernetes guide
# Local testing
pnpm run test:run
# Testing in Docker
docker compose --profile tools run --rm nextjs-testThis setup follows security best practices:
- Non-root user (node / nginx) in production images
- Minimal base images (slim / Alpine where applicable)
- Lockfile-based installs for reproducible builds
- Multi-stage builds to keep final image small
| Variable | Description | Default |
|---|---|---|
PORT |
Application port | 3000 |
NODE_ENV |
Environment mode | development / production |
HOSTNAME |
Next.js server host | 0.0.0.0 |
NEXT_OUTPUT |
Next.js output mode | standalone (or export in export Dockerfiles) |
Create compose.override.yaml for local customizations:
services:
nextjs-dev:
ports:
- "3001:3000"
environment:
- CUSTOM_VAR=value| Command | Description |
|---|---|
pnpm dev |
Start Next.js dev server |
pnpm build |
Build for production |
pnpm start |
Start production server |
pnpm lint |
Run ESLint |
pnpm run test:run |
Run tests once |
pnpm test |
Run Vitest (watch) |
Contributions are welcome. Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
Kristiyan Velkov
- LinkedIn: kristiyan-velkov
- Medium: @kristiyanvelkov
- Newsletter: Front-end World
- X: @krisvelkov
If you find this project helpful, consider supporting:
- GitHub Sponsors
- Buy Me a Coffee
- Revolut