Perl¶

The perl service can host any Perl web application compatible with the PSGI standard.

That includes Perl web frameworks like Mojolicious or Dancer.

Other applications can use the awesome Plack library to implement PSGI. There are also modules to add PSGI hooks to legacy CGI or FastCGI applications.

You can also check those external blog posts:

Basic Use¶

Let’s assume that you are building a DotCloud application called “ramen”. For the sake of simplicity, we will also assume that everything related to this application is located in a directory called “ramen-on-dotcloud”.

Let’s setup our environment:

$ dotcloud create ramen
Created application "ramen"
$ mkdir ramen-on-dotcloud

A DotCloud application is described by a Build Files, which is a simple YAML file named “dotcloud.yml” located in our “ramen-on-dotcloud” directory. To add a new service to our app, we just add the following lines to “ramen-on-dotcloud/dotcloud.yml”:

www:
  type: perl
  approot: helloperl

This Build File instructs the platform to use the code in the subdirectory “helloperl” for our service. Our “ramen-on-dotcloud” directory will have a structure similar to the following one:

ramen-on-dotcloud/
|_ dotcloud.yml   (also known as the "Build File")
|_ helloperl/     (also known as your "approot")
   |_ app.psgi    (mandatory)
   |_ Makefile.PL (optional; can be used to define CPAN dependencies)
   |_ static/     (optional; put your static assets here)
   |_ ...         (all other files: Perl code, etc.)

Let’s generate a sample PSGI application. Run the following on your local machine:

$ cpanm Dancer
[...cpanm downloads and builds Dancer for you...]
$ cd ramen-on-dotcloud
$ dancer -a helloperl
[...dancer creates dancecloud directory with a nice template in it...]
$ echo "require 'bin/app.pl';" > helloperl/app.psgi

We need to add support for PSGI in the application. Just edit Makefile.PL and add Plack in the dependencies, as shown below:

PREREQ_PM => {
    'Test::More' => 0,
    'YAML'       => 0,
    'Dancer'     => 1.3030,
    'Plack'      => 0.9974,
},

We can now push our application to DotCloud:

$ dotcloud push ramen ramen-on-dotcloud/
# upload /home/.../ramen-on-dotcloud/ ssh://dotcloud@uploader.dotcloud.com:21122/ramen
# rsync
[...]
sent 8.11K bytes  received 352 bytes  995.06 bytes/sec
total size is 14.78K  speedup is 1.75
Deployment for "ramen" triggered. Will be available in a few seconds.
2011-06-28 04:27:34 [api] Waiting for the build. (It may take a few minutes)
2011-06-28 04:27:48 [www.0] service booted
2011-06-28 04:27:48 [www.0] The build started
2011-06-28 04:27:48 [www.0] Fetched code revision rsync-1309235251.44
2011-06-28 04:27:51 [www.0] Reloading nginx configuration: nginx.
2011-06-28 04:27:51 [www.0] The build finished successfully
2011-06-28 04:27:51 [api] Deploy finished

Deployment finished successfully. Your application is available at the following URLs
www: http://d07c100d.dotcloud.com/

A random URL has been generated for each web service in your application (it won’t be http://d07c100d.dotcloud.com/ for your app, but something else). Point your browser to this URL to see your new service in action!

If you want to attach a better URL to your application, read the Custom Domains documentation.

Internals¶

Our perl service runs with Nginx as the HTTP frontend. All URLs starting with /static will be served as static files from the (optional) “static” directory as told above. Requests to anything else will be handed to your app through uWSGI and its PSGI module. Supervisor is used to keep the uWSGI daemon up and running.

Dependencies¶

The preferred way to handle dependencies is to write a Makefile.PL, as shown above. When your app is deployed on DotCloud, our custom builder will go through your Makefile.PL and install the required dependencies.

There is also another way to specify dependencies: in the Build File. You can add a requirements section, listing names of packages, and even URLs of packages tarballs – the latter being convenient if you want to install something that is not on CPAN yet.

Example:

www:
  type: perl
  requirements:
    - Some::Thing::On::CPAN
    - http://example.com/something/not/on/cpan/yet.tar.gz

All those dependencies will be handed to cpanm; so “if it can install with cpanm, you can list it in requirements”!

Alternatively, you can call cpanm from the postinstall script. Feel free to use whatever method feels the more convenient for you for those external packages that can’t fit in Makefile.PL.

Custom Nginx Configuration¶

You can specify custom rewrite rules (and actually almost any nginx setting) by creating a file named nginx.conf at the top of your app.

This file will be included by nginx.

Note

You should not include a whole nginx configuration: just the snippets that you need!

A typical example would be:

rewrite ^/search/(.*) /engine/?q=$1 ;

Check out the Nginx wiki to see all available options.

Note

Already have some Apache mod_rewrite RewriteRule statements? All of them can be converted to nginx configuration.