Next.js & Code Deployment: A Beginner's Guide To DigitalOcean

Deploying your Next.js application can seem daunting at first. You’ve built a beautiful website or web application, meticulously crafting its components and functionalities, but now comes the crucial step: making it live for the world to see. This is where deployment comes in, and understanding the process is critical. DigitalOcean offers a straightforward platform for deploying your applications, making it an excellent choice for beginners and experienced developers alike. This guide will walk you through the process of deploying your Next.js application on DigitalOcean, ensuring your project is accessible and performing optimally.

Why DigitalOcean?

DigitalOcean is a cloud infrastructure provider that offers a simple and cost-effective way to deploy and manage your applications. It stands out for several reasons:

Ease of Use: DigitalOcean’s user interface is known for its simplicity, making it easier to navigate and manage your server (Droplet).
Cost-Effectiveness: DigitalOcean offers competitive pricing, making it a good option for projects of all sizes.
Scalability: You can easily scale your resources (CPU, RAM, storage) as your application’s needs grow.
Community Support: DigitalOcean has a strong community and extensive documentation, which is invaluable when you encounter issues.

Choosing DigitalOcean simplifies the deployment process, allowing you to focus on developing your application rather than wrestling with complex infrastructure configurations.

Prerequisites

Before we begin, you’ll need a few things:

A DigitalOcean Account: If you don’t have one, sign up at DigitalOcean. You’ll need to provide payment information.
A Next.js Application: You should have a Next.js project ready to deploy. If you don’t, you can create a new one using the following command in your terminal:

npx create-next-app my-nextjs-app

Basic Knowledge of Terminal/Command Line: You’ll need to navigate directories and run commands.
A Domain Name (Optional, but Recommended): While you can access your application via DigitalOcean’s provided IP address, using a domain name is highly recommended for a professional look and feel. You’ll need to register a domain name with a domain registrar.
Node.js and npm (or yarn) installed locally: These are necessary for building your Next.js application.

Step-by-Step Deployment Guide

Let’s get your Next.js application deployed on DigitalOcean. Here’s a detailed, step-by-step guide:

Step 1: Build Your Next.js Application

Before deploying, you need to build your Next.js application. This process compiles your code and optimizes it for production. Navigate to your project directory in your terminal and run the following command:

npm run build

or if using yarn:

yarn build

This command creates a .next directory in your project, containing the built application files. Make sure this step completes successfully before proceeding.

Step 2: Create a Droplet on DigitalOcean

A Droplet is a virtual private server (VPS) provided by DigitalOcean. It’s where your application will run.

Log in to your DigitalOcean account.
Click on “Create” in the top right corner and select “Droplets.”
Choose an Image: Select an operating system. Ubuntu is a popular and recommended choice. Choose the latest LTS (Long Term Support) version.
Choose a Plan: Select a plan based on your needs. For a basic Next.js application, the smallest plan (e.g., $5/month) is often sufficient to start. You can always upgrade later. Consider factors like CPU, RAM, and storage.
Choose a Datacenter Region: Select a region closest to your target audience for the lowest latency.
Authentication: Choose how you want to access your Droplet. The recommended approach is to use SSH keys. If you don’t have an SSH key, you can generate one using the following command in your terminal (if you are on Linux or macOS) or using tools like PuTTYgen (if you are on Windows):

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

This generates a public and private key pair. Copy the public key (usually found in a file named id_rsa.pub) and paste it into the “SSH keys” section when creating your Droplet. This allows you to securely connect to your server without a password. Alternatively, you can choose password authentication for initial access, but SSH keys are more secure. If using a password, make sure to choose a strong and unique password.

Finalize and Create: Give your Droplet a hostname (e.g., “my-nextjs-app”). Click “Create Droplet.” DigitalOcean will provision your Droplet, which typically takes a minute or two.

Step 3: Connect to Your Droplet via SSH

Once your Droplet is created, DigitalOcean will provide you with its IP address. You’ll use this IP address to connect to your server via SSH (Secure Shell).

Open your terminal and use the following command, replacing your_droplet_ip_address with the actual IP address of your Droplet:

ssh root@your_droplet_ip_address

If you used SSH keys, you might not be prompted for a password. If you used password authentication, you’ll be prompted for the password you set during Droplet creation. If this is your first time connecting, you might see a warning about the authenticity of the host. Type “yes” to continue. You should now be logged into your Droplet’s command line interface.

Step 4: Install Node.js and npm (or yarn) on the Droplet

Your Droplet doesn’t come with Node.js and npm pre-installed. You’ll need to install them.

Update the package list:

sudo apt update

Install Node.js and npm: The easiest way is to use the official NodeSource repository. Run the following commands:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

Replace 18.x with the version you want to install. It’s recommended to use a recent LTS (Long Term Support) version. Then:

sudo apt install -y nodejs

Verify installation: Check that Node.js and npm are installed correctly:

node -v
npm -v

You should see the installed versions printed to the console.

Step 5: Install pm2 (Process Manager)

pm2 is a process manager that will keep your Next.js application running in the background, automatically restarting it if it crashes. This is essential for production deployments.

sudo npm install -g pm2

Step 6: Set Up Nginx (Reverse Proxy)

Nginx is a popular web server that we’ll use as a reverse proxy. It will handle incoming HTTP requests and forward them to your Next.js application, which will be running on a specific port (usually 3000 by default).

Install Nginx:

sudo apt install nginx

Configure Nginx: Create a new configuration file for your application. You can name it after your domain or application. For example:

sudo nano /etc/nginx/sites-available/my-nextjs-app

Paste the following configuration into the file, replacing your_domain.com with your actual domain name (or your Droplet’s IP address if you don’t have a domain yet). Also, make sure the port number (3000) matches the port your Next.js application will be running on.

server {
    listen 80;
    server_name your_domain.com www.your_domain.com; # Replace with your domain

    location / {
        proxy_pass http://localhost:3000; # Assuming your Next.js app runs on port 3000
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Save and close the file. (In nano, press Ctrl+X, then Y, then Enter).

Enable the configuration: Create a symbolic link from the sites-available directory to the sites-enabled directory:

sudo ln -s /etc/nginx/sites-available/my-nextjs-app /etc/nginx/sites-enabled/

Test the Nginx configuration: Make sure there are no syntax errors:

sudo nginx -t

If the test is successful, you’ll see a message indicating this. If there are errors, fix them before proceeding.

Restart Nginx: Apply the changes:

sudo systemctl restart nginx

Step 7: Upload Your Next.js Application

There are several ways to upload your Next.js application to your Droplet. Here are a few common methods:

Using Git: This is the recommended approach if your project is in a Git repository (e.g., GitHub, GitLab, Bitbucket).
Using SCP (Secure Copy): This allows you to securely copy files from your local machine to the Droplet.
Using FTP (File Transfer Protocol): While possible, FTP is generally less secure than the other methods and is not recommended.

Using Git (Recommended):

Create a Git repository on your Droplet: Navigate to the directory where you want to store your application (e.g., /var/www/) and initialize a Git repository:

cd /var/www/
sudo mkdir my-nextjs-app
sudo chown -R $USER:$USER my-nextjs-app
cd my-nextjs-app
git init

Clone your repository: Clone your Git repository from GitHub (or your preferred Git hosting service) to your Droplet. Replace <your_repository_url> with the actual URL of your repository:

git clone <your_repository_url> .

This clones your repository into the current directory (/var/www/my-nextjs-app). The . at the end specifies that the repository should be cloned into the current directory, not into a subdirectory with the repository name.

Install dependencies: Navigate to your application directory and install the dependencies:

cd my-nextjs-app
npm install  # or yarn install

Using SCP (Secure Copy):

Compress your application: Compress your application directory into a ZIP or TAR archive on your local machine. For example:

zip -r my-nextjs-app.zip .

Upload the archive: Use SCP to securely copy the archive to your Droplet. Replace your_droplet_ip_address with your Droplet’s IP address and /path/to/your/local/my-nextjs-app.zip with the actual path to your archive. Also specify the desired destination directory on the server (e.g. /var/www/):

scp /path/to/your/local/my-nextjs-app.zip root@your_droplet_ip_address:/var/www/

Unzip the archive: Connect to your Droplet via SSH. Navigate to the directory where you uploaded the archive (e.g., /var/www/) and unzip it:

ssh root@your_droplet_ip_address
cd /var/www/
unzip my-nextjs-app.zip

Install dependencies: Navigate to your application directory and install the dependencies:

cd my-nextjs-app
npm install  # or yarn install

Step 8: Start Your Next.js Application with pm2

Navigate to your application directory on the Droplet, and start your Next.js application using pm2:

cd /var/www/my-nextjs-app # or wherever your app is located
pm run build # if you haven't already.  Repeat this if you change your code.
pm2 start "npm run start" --name "my-nextjs-app" --watch

or if using yarn

cd /var/www/my-nextjs-app # or wherever your app is located
yarn build # if you haven't already.  Repeat this if you change your code.
pm2 start "yarn start" --name "my-nextjs-app" --watch

Replace “my-nextjs-app” with a name for your application. The --watch flag tells pm2 to automatically restart the application if the code changes. The npm run start command assumes you have a `start` script defined in your `package.json` file. This is usually something like: "start": "next start -p 3000"

Step 9: Configure Your Domain Name (If Applicable)

If you have a domain name, you’ll need to point it to your Droplet’s IP address. This is done through your domain registrar’s DNS settings.

Find your Droplet’s IP address. You can find this in the DigitalOcean control panel.
Log in to your domain registrar’s website.
Go to the DNS settings for your domain.
Create an A record: Create an A record that points your domain (or a subdomain, such as www) to your Droplet’s IP address. The host for the A record is often @ for the root domain (e.g., your_domain.com) and www for the www subdomain (e.g., www.your_domain.com).
Wait for DNS propagation: It can take up to 48 hours for the DNS changes to propagate across the internet, but it usually happens much faster (within a few minutes to a few hours).

Step 10: Access Your Application

Once the deployment and DNS propagation (if applicable) are complete, you should be able to access your Next.js application in your web browser. If you used a domain name, go to your domain (e.g., your_domain.com or www.your_domain.com). If you’re using the Droplet’s IP address directly, enter it into your browser (e.g., http://your_droplet_ip_address).

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

Incorrect Nginx Configuration: Double-check your Nginx configuration file (/etc/nginx/sites-available/your-app-name). Make sure the proxy_pass directive is pointing to the correct port (usually 3000) where your Next.js application is running. Ensure the server_name directive includes your domain name.
Firewall Issues: DigitalOcean Droplets often have a default firewall enabled. Make sure the firewall allows incoming traffic on ports 80 (HTTP) and 443 (HTTPS). You can manage the firewall settings through the DigitalOcean control panel.
Application Not Running: Use pm2 status to check if your application is running. If it’s not, check the logs with pm2 logs my-nextjs-app (replace my-nextjs-app with the name you gave your app) to see if there are any errors. Common errors include missing dependencies or incorrect environment variables.
Missing Dependencies: Make sure you’ve installed all the necessary dependencies for your Next.js application on the Droplet using npm install or yarn install.
Incorrect Permissions: Ensure the user running the Next.js application has the necessary permissions to access the application files.
DNS Propagation Delay: If you’ve just updated your DNS settings, it might take some time (up to 48 hours, although usually much less) for the changes to propagate across the internet.
Build Errors: If you encounter build errors during the npm run build step, carefully review the error messages. These messages often indicate missing dependencies, syntax errors, or other issues in your code. Fix these issues locally and rebuild before deploying again.
Port Conflicts: Make sure no other application is using the same port (usually 3000) as your Next.js application.

Key Takeaways

Deploying a Next.js application on DigitalOcean involves several key steps, including building your application, setting up a Droplet, configuring Nginx, and using pm2 to manage the application process.
Using a reverse proxy like Nginx is essential for handling incoming requests and routing them to your Next.js application.
pm2 is crucial for keeping your application running in the background and automatically restarting it if it crashes.
Properly configuring your DNS settings is essential if you want to use a domain name.
Troubleshooting common issues is a vital part of the deployment process. Reviewing logs and checking configurations can help identify and resolve problems.

FAQ

Can I deploy my Next.js application without a domain name? Yes, you can access your application using your Droplet’s IP address. However, using a domain name is highly recommended for a professional appearance and ease of use.
What is the difference between `npm run build` and `npm run start`? npm run build compiles your Next.js application for production, creating the .next directory with optimized files. npm run start starts the production server, serving the built application.
How do I update my application after deployment? After making changes to your code, rebuild your application (npm run build or yarn build), upload the updated files (e.g., using Git or SCP), and restart the application with pm2 (pm2 restart my-nextjs-app).
How can I secure my application with HTTPS? You can use Let’s Encrypt to obtain a free SSL/TLS certificate and configure Nginx to use HTTPS. This is highly recommended for security.
What if my application crashes? pm2 is configured to automatically restart your application if it crashes. Check the logs (pm2 logs my-nextjs-app) to diagnose the cause of the crash.

Deploying a Next.js application to DigitalOcean provides a robust and scalable solution for bringing your web projects to life. By following these steps and understanding the underlying concepts, you can confidently deploy and manage your applications, ensuring they are accessible to users worldwide. Remember that the process is iterative. You may need to adjust configurations and troubleshoot issues as you go. The rewards of a successful deployment, however, are well worth the effort, allowing you to share your creations with the world and build upon your development skills.

Next.js & Code Deployment: A Beginner's Guide to DigitalOcean