Deploy Next.js Application

Suppose you have a Next.js application that you want to deploy under domain app.domain.com

Prerequisites

• Server connected to FlashPanel
• Domain DNS pointed to the server

Step 1: Install Required Applications

Make sure NodeJS and PM2 are installed on the server. See the installation guide at Application Management.

WARNING

If you use pnpm or yarn as your package manager, install the corresponding application as well via the Application Management page.

Step 2: Create a Website

1. Go to the server management page, click on the Sites menu in the sidebar, then click the Create Website button
2. Enter the domain (e.g., app.domain.com)
3. Enter the Proxy Port — the port your Next.js application runs on (default is 3000)

Step 3: Install Source Code

Install the source code for the website from git or upload it yourself. See the detailed guide at Source Code Installation. To access it, go to the site management page and click on the Source Code menu in the sidebar.

Step 4: Build the Application

Open the server terminal (via SSH or the terminal feature) and navigate to the website directory to install dependencies and build the application:

cd /home/flashpanel/app.domain.com

# Install dependencies
npm install

# Build the production application
npm run build

TIP

Replace app.domain.com with your actual domain.

Step 5: Start the Application

Option A: Using PM2 Dashboard (Recommended)

If you have installed the PM2 application, you can use the PM2 Dashboard on the server management page:

1. Click the Add New button
2. Enter the command: npm start --name my-nextjs-app -- -p 3000
3. Click Start

Option B: Using SSH

You can also start the application manually via SSH:

cd /home/flashpanel/app.domain.com
pm2 start npm --name my-nextjs-app -- start -- -p 3000

WARNING

Make sure the port (3000) matches the Proxy Port you configured when creating the website.

Save PM2 Process List

To ensure your application restarts automatically after a server reboot:

pm2 save

Step 6: Set Up Deployment Script (Optional)

To automate future deployments, you can configure a Deployment Script for your website. A typical Next.js deployment script looks like:

cd /home/flashpanel/app.domain.com
git pull origin main
npm install
npm run build
pm2 restart my-nextjs-app

Updating the Application

When you push new code, you need to rebuild and restart:

• If you have configured a Deployment Script, simply click Deploy in the site management page
• If using the PM2 Dashboard, rebuild manually then click the Restart button for your process
• Or run via SSH:

cd /home/flashpanel/app.domain.com
git pull origin main
npm install
npm run build
pm2 restart my-nextjs-app

Environment Variables

Next.js uses .env files for environment configuration. Create or edit the .env file in your website directory:

cd /home/flashpanel/app.domain.com
nano .env

Add your environment variables:

DATABASE_URL=mysql://user:password@localhost:3306/mydb
NEXT_PUBLIC_API_URL=https://api.domain.com
NODE_ENV=production

WARNING

After changing environment variables, you need to rebuild (npm run build) and restart the application for changes to take effect. Variables prefixed with NEXT_PUBLIC_ are embedded at build time.

Troubleshooting

Application Won't Start

1. Check PM2 logs: use the View Log button in the PM2 Dashboard, or run pm2 logs my-nextjs-app
2. Verify the build was successful: npm run build
3. Check if the port is already in use: sudo lsof -i :3000

502 Bad Gateway

1. Verify the application is running: check PM2 Dashboard or run pm2 status
2. Make sure the application port matches the Proxy Port configured for the website
3. Check application logs for startup errors