How to Seamlessly Install and Run Node.js Apps on HestiaCP: A Complete Guide

Introduction
When managing web applications on a server running HestiaCP, deploying a Node.js app can be tricky, especially if you’re new to the process. I also faced a similar challenge. After much trial and error, I was successfull in installing my node js app to hestiacp server, Thats why i documented this guide to help others streamline the setup. This article will walk you through installing Node.js on HestiaCP, making it globally accessible, and using HestiaCP’s Quick Install App feature to deploy a Node.js app.

Step 1: Access Your Server

Why?
You’ll need to connect to your server to configure Node.js. Root access ensures you have the necessary permissions to make system-wide changes.

Command:

ssh root@192.168.1.23

• Replace 192.168.1.23 with your server’s IP address.

• Once logged in, you’ll operate as the root user.

Step 2: Install NVM (Node Version Manager)

Why?
NVM allows you to manage multiple versions of Node.js easily. This is useful for apps requiring specific Node.js versions.

Command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh

• This command downloads and runs the NVM installation script from its official GitHub repository.

• The curl -o- fetches the script and passes it directly to bash for execution.

Once installed, verify NVM’s presence:

nvm --version

Step 3: Make NVM Globally Available

By default, NVM is installed only for the current user (root in this case). Making it globally available ensures all users can access it.

1. Create a Profile Script for NVM:

cat << 'EOF' > /etc/profile.d/nvm.sh
export NVM_DIR="$HOME/.nvm"
[ -s "/usr/local/nvm/nvm.sh" ] && \. "/usr/local/nvm/nvm.sh"  # This loads nvm
[ -s "/usr/local/nvm/bash_completion" ] && \. "/usr/local/nvm/bash_completion"  # This loads bash_completion
EOF

• This script defines the environment variables required for NVM and enables auto-completion.

2. Relocate NVM to a Shared Directory:

mv /root/.nvm /usr/local/nvm

• Moves NVM to a central location so it’s not tied to the root user’s home directory.

3. Set Permissions for Shared Access:

chown -R root:root /usr/local/nvm
chmod -R 755 /usr/local/nvm

• Grants read, write, and execute permissions for all users to access NVM.

Step 4: Reload Environment Variables

Why?
To ensure the system recognizes the newly configured NVM setup.

Command:

source /etc/profile.d/nvm.sh

• This command reloads the profile script so the changes take effect immediately.

Step 5: Verify NVM Installation

Why?
To confirm NVM is installed and working globally.

1. Switch to a non-root user (e.g., teklog):

   su - teklog

2. Check NVM version:

   nvm --version

• If the version displays correctly, NVM is globally configured.

Step 6: Install the HestiaCP Node.js Plugin

HestiaCP offers a Node.js Quick Install App feature through a plugin, simplifying app deployment.

1. Clone the Plugin Repository:

   cd ~/tmp git clone https://github.com/JLFdzDev/hestiacp-nodejs.git cd hestiacp-nodejs

   • Downloads the Node.js plugin source code to your temporary directory.

2. Run the Installer:

   sudo chmod 755 install.sh sudo ./install.sh

   • This installs the plugin into HestiaCP, enabling Node.js app management.

Step 7: Configure a New Domain for Your Node.js App

1. Create or Edit a User Account:

   • Log in to HestiaCP as admin.

   • Create a new user or edit an existing one, ensuring the user has bash access (SSH Access > bash).

2. Add a Domain:

   • Go to Web > Add Web Domain.

   • Enter your domain name (e.g., example.com).

3. Enable Node.js App:

   • Edit the domain settings and select Quick Install App > Node.js.

   • Configure the following options:

     • Node Version: node 20 or leave default.

     • Start Script: Specify the script from your package.json (e.g., npm run start).

     • Port: Assign a unique port (e.g., 3000).

     • PHP Version: Leave as default (not relevant for Node.js).

Step 8: Install Node.js Using NVM as user

Why?
Node.js needs to be installed in the specific user’s account to support their application.

1. Switch to the target user account:

   su - <username>

   Replace <username> with the user who owns the domain (e.g., webadmin).

2. Load NVM for the user:

   source /etc/profile.d/nvm.sh

3. Install the desired Node.js version (e.g., Node.js 20):

   nvm install 20 nvm use 20

4. Make Node.js 20 the default for this user:

   nvm alias default 20

Step 9: Deploy Your App

1. Upload Your App Files:

• Navigate to nodeapp directory using cd command

cd /home/<user>/<domain>/private/nodeapp

• Use the File Manager or SCP to upload your app files.

1. Install Dependencies:

   • Switch to the app directory:

     cd /home/<user>/<domain>/private/nodeapp

   • Install dependencies:

     npm install

2. Build the App:

   • If required by your app:

     npm run build

Step 9: Start Your App with PM2

Why?
PM2 manages Node.js processes, ensuring your app runs in the background and restarts automatically after crashes or reboots.

1. Install PM2:

   bash

   Copy code

   npm install -g pm2

2. Start the App:

   pm2 start ecosystem.config.js

   This file was create when we used quick install plugin of hestiacp to install the node js app in nodeapp directory.

3. Verify PM2 is Running:

   pm2 list

   • Displays a list of running Node.js apps.

4. Set Up Auto-Start on Reboot:

   pm2 startup

   • Follow the on-screen instructions and run the suggested command as root.

5. Save the Current Process List:

   pm2 save

Step 10: Troubleshooting

• 500 Error:
  Check PM2 logs for errors:

  bash

  Copy code

  pm2 logs

• App Not Responding:
  Ensure the correct port is set in the app and the ecosystem.config.js file.

Conclusion

Deploying a Node.js app on HestiaCP involves installing Node.js for the specific user, configuring the HestiaCP Node.js plugin, and linking the app to the web server. Using PM2 ensures your app runs reliably, making this setup robust and production-ready.

In the next article, we’ll guide you through deploying Ncmaz – Next.js Headless WordPress Blog Magazine on HestiaCP with detailed configurations.

Read the next article here.

How to Run Ncmaz – Next.js Headless WordPress Blog Magazine on HestiaCP