The goal of this guide is to get Perl working on live domain running with Plack.

This is a very basic set up on how to get Plack, Nginx, and Starman aligned if you want to set up a more modern web application in Perl. This means moving away from ye olde CGI.pm and mod_perl. If you see a better way of doing this, then don’t be silent, comment below!

Like many, I was a php developer for years, so getting LAMP stack going was easy. It also not too hard to use CGI and mod_perl, and if this works for you, then please use them. The Perl community can get a bit ornery about their use, and I think they are fine too. However, there is a modern way of doing things that most recommend which is PSGI.

PSGI is a protocol that many PERL frameworks use (Dancer, Mojolicious, Catalyst); however, I wanted to figure how to get it running without framework, because by doing things the hard way, I tend to learn things a lot deeper!

It sounds complicated, and it took weeks for me to set in and figure out. I also nearly crashed my server with trying to set things up. For reference, if my guide doesn’t help see if you can follow these tutorials – they got me on the path to success:

• Why use Plack? If you need a deep read, check out the inventors slide deck: [http://slideshare.net/miyagawa/plack-at-oscon-2010][1]
• This gives you a easy start into learning how to use Plack, our example here is just using hello world example. https://advent.plackperl.org/ (note if you like it, just donate $5 to get the epub)
• You can follow this pretty closely and get your first web app working with Plack instead of Dancer: [https://stackoverflow.com/questions/12127566/an-explanation-of-the-nginx-starman-dancer-web-stack][2]
• Here is the original tutorial I found for Dancer. They used perlbrew, which my system didn’t like. [https://perlmaven.com/getting-started-with-perl-dancer-on-digital-ocean][3]

In truth – after I saw how everything worked – it was a bit of an ‘Ah ha’ moment. Its not particularly complicated, just a new way of thinking.

Part One – Don’t use System Perl

The cool thing about Perl – its likely on your system already. This is how I got back into Perl, because it was already there. However, using your system Perl is probably not a good idea when you are doing active development. Before we install all the Plack goodies, it a good idea to get separate installation of Perl just for our web projects.

There are two Perl install managers that you can have a look at, PerlBrew and Plenv. The Dancer tutorial above used PerlBrew, but my installation was not happy with it, and suffered from constant failed installations, even when force flag was used. So I used Plenv – which worked like a charm. You can try PerlBrew if Plenv doesn’t work.

Note – before you get started, you probably want to set this up as a brand new user, and not root (for security reasons). I’ll leave this up to you, [here is how to create a new user][4]. Once you’ve done that here are steps to install plenv:

The detailed Plenv instructions are on [GitHub][5], here is shorter version for Ubuntu:

Setup plenv into your home directory ~/.plenv (eg /home/.plenv)

1. Clone from Github

   $ git clone https://github.com/tokuhirom/plenv.git ~/.plenv
   

2. Add ~/.plenv/bin to your $PATH for access to the plenv command-line utility.

      $ echo 'export PATH="$HOME/.plenv/bin:$PATH"' >> ~/.profile
   

3. Add plenv to your shell to enable shims and autocompletion

   $ echo 'eval "$(plenv init -)"' >> ~/.profile
   

4. Restart your shell as a login shell so the path changes take effect

    $ exec $SHELL -l

1. Install perl-build, which provides an plenv install command that simplifies the process of installing new Perl versions.

   $ git clone https://github.com/tokuhirom/Perl-Build.git ~/.plenv/plugins/perl-build/
   

2. Almost there – your plenv command should be working now so have look at all the fine versions of Perl it has to offer

   $ plenv install --list
   

A couple of quick tips on deciding. If you choose an odd numbered release its considered unstable You find an install fails, just try another. My system was finicky, but I eventually got there. The install is the longest process.

To install Perl choose a version number form the list and run. Below is the version i used:

$ plenv install 5.30.1

This is potentially a good time to take the dog for a walk! Finally when its done, or whenever you install a cpan module, you have to run this command:

$ plenv rehash

Of you can install this module and it will take care of it for you.

$ plenv install-cpanm

Now check out what versions of Perl you have installed by running “plenv versions” like this:

*system (set by /home/username/.perl-version)
5.30.1

You’ll see the the asterisk by the default system, so you can change this: Set your default developer Perl by

$ plenv local 5.30.1

by doing so you should see that it now goes to your new Perl, note asterisk

system (set by /home/username/.perl-version)
*5.30.1``

You are now ready to install Plack! Quick note – I sometimes noticed that my ‘plenv’ command is not recognised. I run step 5 ($ exec $SHELL -l) and it returns. This was the long part of the set up.

Part 2: Install Plack!

This is pretty easy:

$ cpanm Plack

This took a while to install as well. In addition, it runs a series of test, which some my fail and your install will fail. If that happens try doing a force install (it will explain it should it fail).

Part 3: Install Nginx

I actually made the decision to uninstall my Apache server. I have fond memories of Apache, but wanted a fresh break. If you want to remove [Apache follow this][6]:

$ sudo apt-get remove --auto-remove apache2

if you want to get rid of everything (including local config files)

$ sudo apt-get purge apache2

For installing Nginx here’s a great [blow by blow guide][7] which I’ve whittled down. Refer to the tutorial above for fine tuning.

    sudo apt install nginx #install nginx
    sudo ufw allow 'Nginx FULL' 

We’ll do some more configuration later on.

Part 4: Write your first Plack App

This will be super simple, write of of the Plack Advent Calendar. A simple Hello world. Go to any directory on your server where you will keep your code. Note – you don’t have to keep this in the web document root, in fact, its better if you didn’t (think about the way good old CGI works).

Create this code and save it as hello.psgi (for reference I saved it in /home/perlapps/hello.psgi)

my $app = sub {
    return [ 200, [ 'Content-Type' => 'text/plain' ], [ 'Hello, is it me you're looking for?' ] ];
};

now see it in action:

    ? plackup hello.psgi
    HTTP::Server::PSGI: Accepting connections at http://0:5000/

If you are on your local server go to 127.0.0.1:5000, if your remote server go to :5000 and you should see your message:

**‘Hello, is it me you’re looking for?’**

That’s your first Perl plack script app. But as you can see its not tied to your domain. That’s what where are going to get to!

Part 6: Starman & Nginx

This is the final part. We want Starman to serve our dynamic psgi script and Nginx to serve any static content (think css and images).

Lets do Starman first:

sudo plackup -s Starman -p 5001 -E deployment --workers=10 -a /home/perlapps/hello.psgi

Notice the path to the psgi file we just created above. Next we will configure our website.conf file for nginx. Note if you need to know how to set up set sites in nginx, follow this [tutorial on digital ocean][8]. Here is a mock configuration which sets everthing up:

server {
listen 80;
listen [::]:80;


  root /var/www/gurdyhurdyman.org/html;<br />
  index index.html index.htm index.nginx-debian.html;

  server_name gurdyhurdyman.org www.gurdyhurdyman.org;

  location /css/ {
    alias /var/www/gurdyhurdyman.org/html/files/css/;
    expires 30d;
    access_log off;<br />
  }

  location / {
   proxy_pass        http://localhost:5001;
   proxy_set_header  X-Real-IP  $remote_addr;
   try_files $uri $uri/ =404;<br />
  }

  }

The “location /” bits are the magic parts: nginx will serve all the css files through port 80, while starman gets served via proxy at port 5001.

If you visit your domain (note that gurdyhurdyman.org does not exist), you should see your .psgi file shining through some lyrics from Lionel Richie 🙂