Using custom Node.js versions with Node Version Manager (nvm)

We regularly update Node.js to the latest available versions. Since some applications might not be fully compatible with the latest versions of Node.js, you have the option to run custom Node.js versions using the Node Version Manager (nvm).

Prerequisites

Before you install Node Version Manager, there are a few settings to check and configure on your hosting account:

• Your hosting Control Panel should have a WebApps section. If you do not see a WebApps section, then this tutorial is not suitable for your particular hosting environment. You can contact us via our ticketing system for further assistance.
  
  
•  In the hosting Control Panel > SSH Access section, SSH access and Network tools must be enabled for your account.
  
  

Installation

You need to connect to your account via SSH and follow the steps listed below to install Node Version Manager:

Note: If you wish to install Node Version Manager on an existing WebApps project, skip steps #1 and #2.

1. Create the directory where you wish to install Node Version Manager (e.g. ~/private/nodejscustom), and navigate to it by running the following command:
   
   mkdir /home/$USER/private/nodejscustom && cd /home/$USER/private/nodejscustom
   
   
2. Create the web application where you wish to use a custom Node.js version. You can create the web application using the hosting Control Panel > WebApps section or by running the following command via the sureapp CLI tool:
   
   sureapp project create \
       --engine node \
       --engine-version current \
       --release-dir "/home/$USER/private/nodejscustom" \
       nodejscustom
   
   
   
3. Log into your web application (e.g. nodejscustom) by running the following sureapp CLI command:
   
   sureapp project shell nodejscustom
   
   
4. Next, download and install the latest version of Node Version Manager by executing the following command:
   
   wget https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh && chmod 755 install.sh && ./install.sh && rm install.sh
   Note: If you receive errors about an .npm-global file not existing that prevents the installation, run the below command, and retry the installation command:
   
   npm install -g npm@latest
   
   
5. To load the Node Version Manager for your SSH session, you need to run the following command:
   
   export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" && unset "NPM_CONFIG_PREFIX"
   
   
6. After Node Version Manager (nvm) is installed, you can install custom Node.js versions very easily with the nvm install command. For example, you can use the following command to install Node.js version 18.15.0 on your web application:
   
   nvm install 18.15.0
   
   
7. To change the Node.js version (e.g. to 18.15.0) for your current SSH session, you need to use the following nvm use command:
   
   nvm use 18.15.0
   
   You should see output like the following after executing the command:
   
   Now using node v18.15.0 (npm v9.5.0)
   
   

You can now work on your web application using the desired Node.js version.

Set up custom Node.js version as default for a project

After you have installed Node Version Manager and the desired Node.js version (e.g. 18.15.0) on your project, you have to configure that Node.js version to be used by default. To do this, follow these steps:

1. Create a wrapper script (e.g. ~/private/nodejscustom/start.sh) with the following content:
   
   #!/bin/bash
   killall node
   export NVM_DIR="$HOME/.nvm"
   [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
   unset NPM_CONFIG_PREFIX
   nvm use 18.15.0
   Note: The WebApps Supervisor will not kill the processes associated with the custom Node.js version when the web application is stopped (via the sureapp CLI, the hosting Control Panel > WebApps section, or for a maintenance). That is why the killall node command must be present in the start.sh script to ensure that all node processes (e.g. from a previous execution of the start.sh script) get killed before the web application is actually started.
   
   
2. Grant the wrapper script all necessary permissions with the following command:
   
   chmod 755 ~/private/nodejscustom/start.sh
   
   
3. Add that wrapper script to your web application's start command using the hosting Control Panel > WebApps section. If your web application's start command looks like this:
   
   node app.js
   
   You should alter that start command to set the custom Node.js version and then run your start command/s like this:
   
   /home/YOUR_USERNAME/private/nodejscustom/start.sh && node app.js
   
   Make sure you replace YOUR_USERNAME in the start command with your actual hosting account's username.
   
   

Alternatively, you can add your current start command of the web application as a new line at the end of the start.sh wrapper script and set the start command of the web application to execute only the start.sh wrapper script. For example, the start.sh wrapper script will look like this if you wish to have your web application execute "node app.js" with Node.js version 18.15.0:

#!/bin/bash
killall node
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
unset NPM_CONFIG_PREFIX
nvm use 18.15.0
node app.js


and your start command will look like this:

/home/YOUR_USERNAME/private/nodejscustom/start.sh

You will need to make sure you replace YOUR_USERNAME with your hosting account's username.