Using gulp.js to subtheme Bootstrap Barrio in a cPanel environment

What I needed to do

I develop and maintain several Drupal websites. I do some development on a server running cPanel (in a Linux account that is totally isolated from the account running any production sites), most notably theming work.

I wanted to develop a custom subtheme of the Drupal base theme Barrio (a Bootstrap implementation). Because I like using Sass as a CSS pre-processor, to give me maintainable source files, I wanted to use the Barrio SASS Starter Kit theme as a starter. (It is itself a subtheme of Barrio).

That starter kit uses Gulp to generate the final stylesheets.

So, to do any theming work from a cPanel account, I had to find out how to run Gulp scripts from within cPanel. Gulp runs on node.js.

What I'm about to describe will work with other Drupal themes that use Gulp, and will also work for Drupal themes that need other tools (such as Grunt).

The Red Herring

For cPanel hosting, I have used Veerotech for several years. They are excellent and I highly recomend them. Technical support, when needed, is timely day or night. You talk to actual techs employed by Veerotech themselves (never outsourced). As someone who is fairly competent in web hosting (having run servers myself using various control panels, and no panel), if I need help I'll ask a question that is phrased in the correct technical terminology. Unlike some other providers, they engage me on that level, read and understand the actual question asked, and almost always resolve first time.

In particular, they offer two things, that I thought might have been enough. 1. With only a helpdesk ticket and a five minute wait, any account can have console / shell access. 2. Their CloudLinux setup includes the tool to create a Node application within the cPanel UI, including allowing you to run it from an external (sub)domain if you want an actual website powered by Node.

I don't need public access, but I hoped that this access to Node might give me a way to run the Gulp script from my Barrio subtheme.

Alas, no. The cPanel / CloudLinux Node application system assumes you'll be running Node only from within the directory where you create your app. If I tried to run the Gulp script for my theme, it couldn't see dependent modules (like PostCSS). So this was not the answer.

But I found a solution that works, and it's really quite easy when you know how. In fact, it's elegant and cleaner than creating a Node application that is accessible (but does nothing) from the public internet. Here's how:

Node Version Manager

Node Version Manager is a package that, in its own words, "a version manager for node.js, designed to be installed per-user, and invoked per-shell. nvm works on any POSIX-compliant shell (sh, dash, ksh, zsh, bash), in particular on these platforms: unix, macOS, and windows WSL."

The important bit is "per-user". It is installed by the user wanting to run it, in the shell they wish to use. Root permissions are not needed.

Step 1: Install Node Version Manager

The docs tell you to run one of these two commands.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash

Personally, I never pipe curl or wget straight into a shell command. Should the download be corrupted or fail to finish, you could accidentally run half a script and leave things in an unstable state. So I did this:

wget https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh
bash install.sh

The version number (0.37.2) was current at the time I ran the install script. Obviously, use the download current when you run it.

This will install Node Version Manager into a directory within your home named .nvm , and attempt to append lines to your .bashrc file that sets up the environment and path for future use. It also prints to screen how to run those commands yourself, in case you don't wish to log back into the shell (or source .bashrc).

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Step 2: Install Node.js

In theory, you just run

nvm install node

I tried that first, but hit a problem. The gulp script for the Barrio subtheme calls node-sass.

In particular, it called version 4.14.1 of node-sass, which threw an error because that version does not support 15.x releases of Node.js. By the time read this, a different version of node-sass may be called (5.0.0 does support Node.jx 15). So you may be able simply to run the command above.

In my case, I had to look at the release notes for node-sass 4.14.1, and see that the highest supported version of Node.js was 14. I then went to the table of releases for Node.js where I saw that meant installing Node.js 14.15.4. That should be possible with

nvm install 14.15.4

but for some reason that hung without completing. The release table also told me that 14.15.4 was the current long-term support version, so I ran this command without any trouble:

nvm install --lts

Step 3: Install the required modules for the project

I was now able to call the commands on the Barrio SASS project page. Install both Bootstrap Barrio and Barrio SASS, run the command included with Barrio SASS to create your own subtheme, navigate to the your custom theme directory, and run these two commands:

npm install --global gulp-cli
npm install

Step 4: Call gulp

Now, you just go to your custom theme directory and run:

gulp

That will pick up gulpfile.js in the project directory and compile the theme resources. It will then stay running, because the gulpfile includes gulp-watch, which means it will watch for when you change any of the .scss files and instantly rebuild the theme. So you may prefer to run

gulp &

to keep it in the background.

The Gulp script will also think you're running a full version of Node.js, which means it will attempt to launch a web serving process listening on a particular port on the localhost interface. None of that will work in a shared hosting environment. That's OK - you don't need it to. You just need Gulp to assemble the css files for your theme, which it will do.