Ruby Gems and Node tools (Compass, Gulp, Grunt, Bower)

Some theme workflows build their CSS or assets with tooling that isn't part of Drupal itself — Sass or Compass on the Ruby side, or Gulp, Grunt and Bower on the Node side. BOA can run all of it directly in your oN.ftp shell, so there's no compile-locally-and-upload loop. One control file switches the toolchain on for your account; from there it's ordinary gem and npm work.

This is optional, and separate from the .dev. preview URL and Twig debugging that the rest of the development workflow is built on — reach for it only if your theme's build actually uses these tools.

Sass / Compass: Ruby tooling in your shell

If your theme builds its CSS with Sass or Compass, you can run that toolchain directly in your oN.ftp shell — no compile-locally-and-upload loop. Ruby and the gem machinery are provided by the server; you switch them on for your account with a single control file:

touch ~/static/control/compass.info

Then log out, give it up to five minutes, and log back in. The tooling is installed for your account in the background, and a fresh login picks up the new paths. A few gems can't build their native extensions inside the limited shell, so BOA pre-installs those problem gems for you automatically as part of that setup — you don't have to do anything about them. (At the time of writing that pre-installed set includes bluecloth, eventmachine, ffi, hitimes, http_parser.rb, oily_png and yajl-ruby.) From there it's ordinary gem work:

gem install --conservative compass
cd ~/platforms/my-platform/sites/all/themes/mytheme
bundle install     # if the theme ships a Gemfile — Bundler comes preinstalled
compass watch      # or: compass compile

gem-list shows the gems your account has — run it after your account is initialized, though: before then it can still show an old, system-wide gem list, and only once your account is set up does it list just your own local Ruby and gems. Run the tools directly (compass watch, guard start) rather than through a Drush wrapper — wrappers that open a sub-shell (like drush omega-guard) don't work in the limited shell.

The control file enables Ruby for your main account and any client sub-accounts on your instance — and because each sub-account gets its own copy of the gems, initialization takes a little longer the more sub-accounts you have. Deleting ~/static/control/compass.info removes the gems from all of them again a few minutes later (and, where Node is enabled, the NPM setup from the next section too).

A few notes:

• If you've been around BOA long enough to remember RVM: it's gone. The old per-user RVM setup was replaced by a single server-provided Ruby, so any guide that begins "install RVM" no longer applies — the control file above is the entire setup. In the same vein, an account whose Ruby was first initialized back before BOA-5.4.0 should be reinitialized once to land on the current layout: delete ~/static/control/compass.info, wait until compass --version stops working, then touch the file again.
• If gem still isn't available well after five minutes and a fresh login, the Ruby toolchain may simply not be enabled on your server — it's an optional server-side extra. A short support request to your host sorts that out. (Running your own server? Ruby and Compass are the CSS xtra — see the XTRAS list (for operators).)
• If bundle install says it can't build a native extension for a gem that gem-list already shows as installed, compare the versions — the copy BOA pre-installed often differs from the one pinned in your theme's Gemfile.lock. Point the lock file at the installed version and run bundle install again, or reinitialize Ruby to land on a different build: delete ~/static/control/compass.info, wait until compass --version stops working, then touch the file again.

Gulp, Grunt and Bower: NPM tooling in your shell

The same control file has a second job. On servers where Node.js is enabled, ~/static/control/compass.info also sets up NPM for your account, so theme toolchains built on Gulp, Grunt or Bower run in your shell just like the Ruby ones above.

Node is a server-side option, and it is off by default — node is powerful enough to step around the limited shell's guard rails, so BOA only allows it where that's a sensible trade-off (on hosted BOA, typically single-tenant plans). The reliable way to check whether your server has it is to ask the tool itself:

npm --version

If that answers with a version, Node is enabled and the control file does the rest. If not, the control file alone won't add it — enabling Node is a change your host makes at the server level, so ask them. Don't read too much into npm appearing in the ? / help command list, though: on some server plans the names are listed even where Node isn't actually installed. (Running your own server? It's the NPM xtra plus an explicit root opt-in — see the XTRAS list (for operators).)

Where Node is enabled, the same touch ~/static/control/compass.info and re-login routine from the previous section provisions NPM alongside Ruby:

• You get your own package home at /opt/user/npm/oN.ftp/. npm's global prefix is pointed at .npm-packages inside it, via a ~/.npmrc you'll find locked read-only — that's deliberate, so -g installs always land in your own package home instead of trying (and failing) to write to the system.
• Every shell login puts that prefix's bin directory on your PATH automatically — which is what makes a freshly installed tool runnable by name, no re-login needed.

So install "globally" exactly as the tools' own documentation says — no sudo, no path juggling:

npm install -g gulp
npm install -g grunt
npm install -g bower
gulp --version      # on your PATH immediately, by name

Two differences from the Ruby side are worth knowing:

• Main account only. NPM is provisioned for your oN.ftp login only. Client sub-accounts get their own Ruby gems from the same control file, but never Node/NPM.
• Deleting compass.info removes it all. Dropping the control file wipes your /opt/user/npm/oN.ftp/ package home a few minutes later — including everything you've installed with npm install -g. If you initialize again later, reinstall your tools.

One pleasant side effect worth knowing: servers that allow Node also allow scp in the limited shell — which is why scp file copies work on some BOA servers and not others.

Related

• Developing your site — the .dev. preview URL, Twig and Drupal 7 theme debugging, and which settings files are yours to edit.
• Building your own platform — bringing your own codebase in as a platform to develop the theme against.
• Shell and SFTP access — connecting as oN.ftp so you can run gem and npm in the first place.
• XTRAS list — the operator-side CSS and NPM xtras behind Ruby and Node (for operators).