Deploying a Next.js App with Docker on a VPS: A Complete Guide

Introduction

In this blog post, you'll learn how to deploy a Next.js application using Docker on a Virtual Private Server (VPS). This guide will cover creating a Docker image, uploading it to GitHub Container Registry (GHCR), and deploying it on a VPS.

1. Preparing the Next.js App for Docker Deployment

1.1. Configure next.config.mjs

Ensure your Next.js app is packaged properly for Docker by setting the output configuration to 'standalone' in the next.config.mjs file.

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
};

export default nextConfig;

1.2. Create a Dockerfile

Create a Dockerfile in the root of your Next.js project to build the Docker image. This example uses multi-stage builds for efficiency and security.

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
elif [ -f package-lock.json ]; then npm ci; \
elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
else echo "Lockfile not found." && exit 1; \
fi

# Build the Next.js app
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN if [ -f yarn.lock ]; then yarn run build; \
elif [ -f package-lock.json ]; then npm run build; \
elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
else echo "Lockfile not found." && exit 1; \
fi

# Production image, copy built files and run the app
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD HOSTNAME="0.0.0.0" node server.js

1.3. Create a .dockerignore File

To optimize the Docker build process, create a .dockerignore file to exclude unnecessary files and directories.

Dockerfile
.dockerignore
node_modules
npm-debug.log
README.md
.next
.git

2. Building and Uploading the Docker Image

2.1. Build the Docker Image for linux/amd64

To build the Docker image and ensure compatibility with most VPS environments, use the following command:

docker build --platform linux/amd64 -t ghcr.io/your-username/your-image-name .

Replace your-username with your GitHub username and your-image-name with your chosen Docker image name.

2.2. Log in to GitHub Container Registry (GHCR)

Before pushing the Docker image to GHCR, log in with a personal access token (PAT) from GitHub.

echo "YOUR_GITHUB_TOKEN" | docker login ghcr.io -u "your-username" --password-stdin

Replace YOUR_GITHUB_TOKEN with your GitHub PAT and your-username with your GitHub username.

2.3. Push the Docker Image to GHCR

After logging in, push the Docker image to GitHub Container Registry:

docker push ghcr.io/your-username/your-image-name:latest

3. Deploying the Docker Image on a VPS

3.1. SSH into the VPS

Use SSH to access your VPS. The command typically looks like this:

ssh user@your-vps-ip-address

Replace user with your VPS username and your-vps-ip-address with the IP address of your VPS.

3.2. Install Docker on the VPS

If Docker is not installed on your VPS, use these commands to install it (for Ubuntu-based distributions):

sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

3.3. Log in to GHCR from the VPS

Log in to GitHub Container Registry from your VPS:

echo "YOUR_GITHUB_TOKEN" | sudo docker login ghcr.io -u "your-username" --password-stdin

3.4. Pull and Run the Docker Image on the VPS

To deploy the Docker container on the VPS, pull the Docker image from GHCR:

sudo docker pull ghcr.io/your-username/your-image-name:latest

After pulling the image, run the Docker container, exposing port 3000:

sudo docker run -p 3000:3000 ghcr.io/your-username/your-image-name:latest

3.5. Set Up Docker to Run at Startup (Optional)

If you want the Docker container to start when the VPS boots, you can use a systemd service or Docker's restart policies.

Conclusion

This guide covered the essential steps for deploying a Next.js app using Docker on a Virtual Private Server. By following these steps, you can ensure a smooth deployment process and maintain flexibility in managing your application.