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.
- 🔥 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 --buildAccess at http://localhost:3000
Production (static export + Nginx)
docker compose up nextjs-export --buildAccess at http://localhost:8080
Note: 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