Complete Docker Setup Guide for Next.js on VPS

Deploying Next.js applications on a VPS can be challenging, but Docker makes it much easier by providing consistent environments and simplified deployment. This guide will walk you through setting up a production-ready Next.js application with Docker on a VPS.

Prerequisites

Before we begin, make sure you have:

A VPS with Ubuntu 20.04 or later

SSH access to your VPS

A Next.js application ready to deploy

Basic knowledge of Linux commands

Step 1: Install Docker on Your VPS

First, connect to your VPS via SSH and install Docker:

bash(22 lines, showing 15)

1# Update package index
2sudo apt update
3 
4# Install prerequisites
5sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
6 
7# Add Docker's official GPG key
8curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
9 
10# Add Docker repository
11echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
12 
13# Install Docker
14sudo apt update
15sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Step 2: Create Dockerfile for Next.js

In your Next.js project root, create a Dockerfile:

dockerfile(47 lines, showing 15)

1# Use the official Node.js runtime as base image
2FROM node:18-alpine AS base
3 
4# Install dependencies only when needed
5FROM base AS deps
6RUN apk add --no-cache libc6-compat
7WORKDIR /app
8 
9# Copy package files
10COPY package.json package-lock.json* ./
11RUN npm ci
12 
13# Rebuild the source code only when needed
14FROM base AS builder
15WORKDIR /app

Step 3: Configure Next.js for Standalone Output

Update your next.config.js to enable standalone output:

javascript

1/** @type {import('next').NextConfig} */
2const nextConfig = {
3  output: 'standalone',
4  // Other config options...
5}
6 
7module.exports = nextConfig

Step 4: Create docker-compose.yml

Create a docker-compose.yml file for easier management:

yaml(22 lines, showing 15)

1version: '3.8'
2 
3services:
4  nextjs:
5    build:
6      context: .
7      dockerfile: Dockerfile
8    container_name: nextjs-app
9    restart: unless-stopped
10    ports:
11      - "3000:3000"
12    environment:
13      - NODE_ENV=production
14      - NEXT_PUBLIC_API_URL=https://api.yourdomain.com
15    volumes:

Step 5: Create .dockerignore

Create a .dockerignore file to exclude unnecessary files:

dockerignore

1node_modules
2.next
3.git
4.gitignore
5README.md
6.env*.local
7npm-debug.log*
8yarn-debug.log*
9yarn-error.log*
10.DS_Store
11*.pem

Step 6: Build and Run Docker Container

On your VPS, clone your repository and build the Docker image:

bash

1# Clone your repository
2git clone https://github.com/yourusername/your-nextjs-app.git
3cd your-nextjs-app
4 
5# Build the Docker image
6docker compose build
7 
8# Run the container
9docker compose up -d
10 
11# Check if container is running
12docker ps
13 
14# View logs
15docker compose logs -f

Step 7: Set Up Nginx Reverse Proxy (Optional)

For production, set up Nginx as a reverse proxy:

bash

1# Install Nginx
2sudo apt install -y nginx
3 
4# Create Nginx configuration
5sudo nano /etc/nginx/sites-available/nextjs

Add this configuration:

nginx(16 lines, showing 15)

1server {
2    listen 80;
3    server_name yourdomain.com www.yourdomain.com;
4 
5    location / {
6        proxy_pass http://localhost:3000;
7        proxy_http_version 1.1;
8        proxy_set_header Upgrade $http_upgrade;
9        proxy_set_header Connection 'upgrade';
10        proxy_set_header Host $host;
11        proxy_cache_bypass $http_upgrade;
12        proxy_set_header X-Real-IP $remote_addr;
13        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
14        proxy_set_header X-Forwarded-Proto $scheme;
15    }

Enable the site and restart Nginx:

bash

1sudo ln -s /etc/nginx/sites-available/nextjs /etc/nginx/sites-enabled/
2sudo nginx -t
3sudo systemctl restart nginx

Step 8: Set Up SSL with Let's Encrypt

Secure your application with SSL:

bash

1# Install Certbot
2sudo apt install -y certbot python3-certbot-nginx
3 
4# Obtain SSL certificate
5sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
6 
7# Auto-renewal is set up automatically

Best Practices

1. Use Multi-stage Builds

Multi-stage builds reduce the final image size significantly.

2. Set Environment Variables Securely

Use Docker secrets or environment files for sensitive data:

yaml

1services:
2  nextjs:
3    env_file:
4      - .env.production

3. Health Checks

Add health checks to your docker-compose.yml:

yaml

1services:
2  nextjs:
3    healthcheck:
4      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/api/health"]
5      interval: 30s
6      timeout: 10s
7      retries: 3
8      start_period: 40s

4. Resource Limits

Set resource limits to prevent resource exhaustion:

yaml

1services:
2  nextjs:
3    deploy:
4      resources:
5        limits:
6          cpus: '1'
7          memory: 1G
8        reservations:
9          cpus: '0.5'
10          memory: 512M

5. Log Management

Configure log rotation:

yaml

1services:
2  nextjs:
3    logging:
4      driver: "json-file"
5      options:
6        max-size: "10m"
7        max-file: "3"

Troubleshooting

Container won't start

Check logs: docker compose logs nextjs

Port already in use

Change the port mapping in docker-compose.yml or stop the conflicting service.

Build fails

Ensure all dependencies are in package.json and check Node.js version compatibility.

Conclusion

You now have a production-ready Next.js application running on your VPS with Docker. This setup provides:

Consistency - Same environment across development and production

Isolation - Application runs in its own container

Scalability - Easy to scale horizontally

Maintainability - Simple updates and rollbacks

Remember to keep your Docker images updated and monitor your application's performance regularly.

Complete Docker Setup Guide for Next.js on VPS

Complete Docker Setup Guide for Next.js on VPS

Prerequisites

Step 1: Install Docker on Your VPS

Step 2: Create Dockerfile for Next.js

Step 3: Configure Next.js for Standalone Output

Step 4: Create docker-compose.yml

Step 5: Create .dockerignore

Step 6: Build and Run Docker Container

Step 7: Set Up Nginx Reverse Proxy (Optional)

Step 8: Set Up SSL with Let's Encrypt

Best Practices

1. Use Multi-stage Builds

2. Set Environment Variables Securely

3. Health Checks

4. Resource Limits

5. Log Management

Troubleshooting

Container won't start

Port already in use

Build fails

Conclusion

Enjoyed this article?

Stay Updated

Related Articles

Top 10 Must-Have Developer Tools in 2025

JSON Best Practices for Modern Applications