Deploying Next.js on Your Own VPS With Docker

Running modern web applications in production requires infrastructure that you can fully control without paying unpredictable cloud scaling fees. When you want to deploy Next.js VPS Docker setups provide an isolated, reproducible environment that eliminates differences between your local development machine and your production server. This guide is written for founders, developers, and tech leads who want a straightforward, maintainable deployment pipeline for their Next.js applications without relying on proprietary platform-as-a-service providers.

Understanding the Architecture

Before writing any configuration files, it helps to understand what we are building. A standard Next.js application requires a Node.js runtime environment to handle server-side rendering, API routes, and incremental static regeneration. By containerizing this application with Docker, we bundle the runtime, dependencies, and code into a single image.

On your Virtual Private Server, Nginx typically sits at the edge as a reverse proxy, handling incoming SSL termination and forwarding traffic to the local port where your Docker container listens. This architecture gives you the flexibility to scale vertically by upgrading your server resources or horizontally by adding more containers behind a load balancer as your traffic grows.

Preparing Your Next.js Application for Docker

The first step in containerization is configuring your Next.js project to support standalone output. Open your next.config.js file and add the output property set to standalone. This tells the Next.js build system to trace all required dependencies and create a minimal folder containing only what is needed to run the production server.

Next, you need to create a multi-stage Dockerfile in the root of your repository. Multi-stage builds are essential for keeping your production image size small and secure. The first stage installs all dependencies and builds the application, while the final runtime stage copies only the compiled output and production node_modules, discarding unnecessary build tools and source code.

Writing the Production Dockerfile

Create a file named Dockerfile in your project root. A robust production setup usually consists of four distinct stages: dependencies, builder, runner, and a lightweight base image.

Here is what your builder stage needs to accomplish:

• Use an official Node.js alpine image for a minimal footprint.
• Set your working directory inside the container.
• Copy package.json and lock files to install dependencies using clean npm ci commands.
• Copy your application source code and execute the build command with environment variables in place.

In the runner stage, you configure a non-root user for security best practices, expose the default Next.js port 3000, and define the startup command to launch the standalone server.js file.

Configuring Nginx and SSL on Your VPS

With your Docker container running locally on the server port, you need to configure Nginx to route public web traffic to it securely. Install Nginx and Certbot on your Ubuntu or Debian VPS to handle Let's Encrypt SSL certificates.

Create a new server block configuration file in your sites-available directory. Define your domain name, point your SSL certificate paths, and configure the proxy_pass directive to point to http://localhost:3000. Ensure you include standard proxy headers like Host, X-Real-IP, and X-Forwarded-For so your Next.js application receives the correct client connection details.

Automating Deployments

Manual server deployments invite human error. Once your manual setup is stable, you should automate the build and release process. You can use GitHub Actions to trigger a workflow whenever code is pushed to your main branch. This workflow can securely SSH into your VPS, pull the latest code repository, rebuild the Docker image, and restart the container with zero downtime using Docker Compose.

If your project requires comprehensive custom infrastructure beyond basic server hosting, our team can assist through our web development, SEO and marketing services to ensure your digital assets perform at their absolute best.

Key takeaways

• Using standalone output in Next.js drastically reduces your Docker image size.
• Multi-stage builds keep your production environment secure and free of heavy development dependencies.
• An Nginx reverse proxy is essential for handling SSL certificates and routing traffic to your container.
• Automating your workflow with GitHub Actions prevents human error during server updates.

Frequently asked questions

Why use Docker for a Next.js deployment instead of running Node.js directly?

Docker ensures that your application runs in an identical environment from development to production, eliminating dependency version conflicts and operating system discrepancies.

How do I handle environment variables in a Dockerized Next.js app?

Environment variables can be passed at build time for public variables prefixed with NEXT_PUBLIC_ or at runtime via a .env file mounted into your Docker Compose configuration for server-side secrets.

Can I run multiple Next.js websites on a single VPS?

Yes. You can run multiple containers on different internal ports and use Nginx server blocks with distinct domain names to route traffic to the correct container.