Running a Mojolicious non-lite app on a cPanel VPS server

I've used cPanel/WHM for a very long time as a personal server manager, and up until recently it's served my purposes pretty well.

However since getting into the Mojolicious framework and a few other Perl modules that require a Perl version greater than the 5.8 that cPanel is currently tied into, it's become a bit of a nightmare trying to run any Modern Perl apps on it.

While there is some Mojolicious documentation around running an app on Apache, I thought I'd document the exact steps I took to get a non-lite app up & running on my Hostgator server (although I'm sure it would work equally well for Dreamhost etc or other shared hosting solutions):

The steps I took were:

  1. Install perlbrew in the user account (not root) you want to run the Mojolicious app on
    • Append the following to your ~/.bash_profile file to add the perlbrew command to your path (then exit & reload your shell):
      source ~/perl5/perlbrew/etc/bashrc
  2. Install Perl 5.10+ using perlbrew (you may need to use the --force option). Then switch to that version by default (as per instructions on the perlbrew website)
  3. Install Mojolicious and any other required modules using cpan minus (the main CPAN app crashed on my VPS)
  4. Change the shebang line in your main Mojolicious Perl script (ie script/appname) to point to the perlbrew version in use. I set up a symlink in the user's home directory for this as the path was quite long (see below).
    • You may also want to add a symlink to the relevant lib directory if you find it's not in the @INC path (also see below).
  5. Edit your .htaccess file - this required a lot of fiddling around but this worked for me:
# set apache handler to treat your specified script name(s) as a CGI program
Options +ExecCGI
<Files ~ "(appname)$">
  SetHandler cgi-script

# rewrite any requests into the app
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ script/appname/$1 [L]

  1. Then you need to alter the main script's shebang line and add 1-2 more lines to the top of your script:
# in my case the above points to:
# /home/username/perl5/perlbrew/perls/perl-5.16.2/bin/perl

# set env variable to use root for pretty URLs

# cpanm in perlbrew appears to install into the following directory by default:
# /home/username/perl5/lib/perl5/
# this isn't in perlbrew's @INC path it seems so I set up a symlink and added a 'use lib' statement
use lib qw(/home/username/user-perl-lib-symlink);

All being well this should give you a fully functioning Mojolicious app behind a default Apache install, on a limited access cPanel shared or VPS server.

If you've got any improvements to this process I'd love to hear them!

* Credit to the thread on Google Groups for a couple of these fixes:


The next major release of cPanel will ship with a much more recent perl:

On simple shared hosting but with SSH access
One can also use ActivePerl with the same success.
Here is an example:
In your scrips you can simply have:
#!/usr/bin/env perl
provided that you have added the folder with your perl to your $PATH environment variable

Leave a comment

About Rob Hammond

user-pic I blog mostly about SEO, but sometimes about Perl.