FlashPanel

Deploy a Node.js application ​

Suppose you have a Node.js application (Express, Fastify, NestJS…) that you want to run under the domain api.domain.com, and the application listens on port 3000. The website on FlashPanel acts as a reverse proxy: it receives requests for the domain and forwards them to port 3000 of your application, while PM2 keeps the application running.

Prerequisites ​

  • Server connected to FlashPanel
  • Domain DNS pointed to the server's IP
  • Your application reads its listening port from configuration (for example the PORT environment variable) or listens on a fixed port you know in advance

Step 1: Install Required Applications ​

Go to the server management page, click the Apps menu, select the Not Installed tab, then install NodeJS (pick the Node.js version your application needs) and PM2. See Applications for details.

TIP

If your project uses pnpm or yarn, also install the corresponding application on the Apps 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., api.domain.com)
  3. Enter the Proxy Port: the port your Node.js application listens on, for example 3000
  4. Click Create Site

TIP

If you enable Website Isolation, the website runs as its own Linux user. In that case, replace flashpanel in the paths and commands below with the website's isolation username.

Step 3: Upload the Source Code ​

Choose one of the following:

  • From Git (recommended): on the site management page, click the Install Source Code menu and install your repository. See Source Code Installation. This lets you redeploy with one click from the Deployments page.
  • Upload it yourself: open File Manager on the website's overview page and upload your code to the website directory. See File Manager.

The source code lives in /home/flashpanel/api.domain.com.

Step 4: Install Dependencies ​

Open Terminal on the website's overview page (the terminal logs in as the user that owns the website and opens the website directory), then run:

bash
cd /home/flashpanel/api.domain.com

# Install production dependencies
npm install --omit=dev

# If your project uses TypeScript or needs a build step, install all dependencies and build
# npm install
# npm run build

If your application uses a .env file, create or edit it in the website directory (with File Manager or nano .env) and set the port to match the Proxy Port:

properties
PORT=3000
NODE_ENV=production

Step 5: Start the Application with PM2 ​

Option A: Using the PM2 page (Recommended) ​

  1. Go to the server management page, click the PM2 menu, then click the Add New button
  2. In Website Isolation Username, select the user that owns the website (flashpanel by default)
  3. In the command field (it already has the pm2 start prefix), enter the full path to the entry file, a process name and the working directory, for example: /home/flashpanel/api.domain.com/index.js --name my-api --cwd /home/flashpanel/api.domain.com
  4. Click Start

If your application starts with npm start, enter a command like: npm --name my-api --cwd /home/flashpanel/api.domain.com -- start

Option B: Using SSH ​

Log in via SSH as the user that owns the website (or use the website's Terminal) and run:

bash
cd /home/flashpanel/api.domain.com
pm2 start index.js --name my-api

WARNING

The port your application listens on must match the website's Proxy Port. Make the application listen on 127.0.0.1 (or localhost) instead of 0.0.0.0 so it only receives requests through the website and is not exposed directly to the Internet.

Save PM2 Process List ​

To make the application start again 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 (for example in Terminal on the server's overview page; 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) ​

If the source code was installed from Git, you can automate future updates with a Deployment Script. On the site management page, click the Deployments menu, edit the Deploy Script section, then click Update. For example:

bash
cd /home/flashpanel/api.domain.com
git pull origin main
npm install --omit=dev
pm2 restart my-api

Verify the Result ​

  1. On the PM2 page, the my-api process shows the online status
  2. Visit https://api.domain.com and check that your application responds correctly

Updating the Application ​

  • If you have configured a Deployment Script, click Deploy Now in the Deployments menu of the website
  • If you upload code manually, reinstall dependencies after uploading the new version (if they changed), then click the process's Restart button on the PM2 page, or run pm2 restart my-api

Troubleshooting ​

Application Won't Start ​

  1. Click the process's View Log button on the PM2 page, or run pm2 logs my-api
  2. Run the application directly in the website directory to see the error: node index.js
  3. Check whether another program already uses the port: ss -tln | grep 3000

502 Bad Gateway ​

  1. Check that the process is running on the PM2 page or with pm2 status
  2. Make sure the port your application listens on matches the website's Proxy Port
  3. See also 502 Bad Gateway

Application Does Not Start After a Server Reboot ​

Repeat Save PM2 Process List as the user that owns the website.