FlashPanel

Appearance

Deploy a Next.js application ​

Suppose you have a Next.js application that you want to deploy under the 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 the Sites menu in the sidebar, then click the New Site button
  2. Enter the Domain Name (e.g., app.domain.com)
  3. Enter the Proxy Port: the port your Next.js application runs on (default is 3000)
  4. Click Create Site

Step 3: Install Source Code ​

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

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:

bash
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 ​

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

  1. Click the Add New button
  2. In Website Isolation Username, select the user that owns the website (flashpanel by default)
  3. Enter the command: npm --name my-nextjs-app --cwd /home/flashpanel/app.domain.com -- start -- -p 3000
  4. Click Start

Option B: Using SSH ​

You can also start the application manually via SSH:

bash
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, log in via SSH as the user that owns the website and run:

bash
pm2 startup

This command prints a command that starts with sudo env PATH=.... Run that command as root (you only need to do this once), then save the process list:

bash
pm2 save

Step 6: Install SSL ​

On the site management page, click the SSL menu and install a certificate for the domain. See SSL.

Step 7: 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:

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

Verify the Result ​

  1. On the PM2 page, the my-nextjs-app process shows the online status
  2. Visit https://app.domain.com and check that the pages render correctly, including images and static files

Updating the Application ​

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

  • If you have configured a Deployment Script, simply click Deploy Now in the Deployments menu of the site management page
  • If you use the PM2 page, rebuild manually, then click the Restart button of your process
  • Or run via SSH:
bash
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:

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

Add your environment variables:

properties
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 on the PM2 page, 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 the PM2 page 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

Images Not Displaying ​

If your Next.js images or static assets are not displaying correctly, you may need to add a custom Nginx configuration (the snippet below only works with Nginx).

  1. Go to the site management page
  2. Click the Nginx menu in the sidebar
  3. Click the Add Custom Config button and select In Block Server under Position
  4. Add the following configuration (replace app.domain.com with your actual domain):
nginx
location ^~ /_next/static {
    alias /home/flashpanel/app.domain.com/.next/static;
}
  1. Click Save and then click the Sync button at the top to apply the changes.