[Dancer-users] developing many Dancer apps coexisting with Apache apps

[P Kishor]

I have finally got everything working correctly (the status() bug
still exists), and have typed up the following notes. Please feel free
to add them to the Dancer Deployment.pod if you think they will be
helpful to others. I spent a lot of time getting to this point, so I
think these notes will be helpful to others.

-----
Once we have downloaded Dancer, generated a project scaffolding, fired
up dance.pl, and visited our website at http://localhost:3000/, we are
faced with several decisions --

How am I going to serve this on my web server?
Will I be able to have multiple Dancer-powered sites?
How will this integrate with Apache?

A typical web application developer is working on several applications
on her development machine. If she is smart and lucky, her development
machine is identical to her production server, so she doesn't have to
second guess differences in modules, software versions and directory
layouts. Still, there are a few differences.

Under the Apache scenario, her web sites in development are stored on
her computer under

    ~/Sites/app0
    ~/Sites/app1
    ~/Sites/app2

She is accessing her web sites on her development machine via URIs
that look like

    http://localhost/app0
    http://localhost/app1
    http://localhost/app2

Apache is listening on the default port 80, and serving everything
under ~/Sites as the DocumentRoot by simply adding $app_dir to
http://localhost

With the arrival of Dancer, the out-of-box model is different. For all
purposes, dance.pl is the web server, and is listening on port 3000 by
default. But, there cannot be multiple web servers on one port. So,
she modifies the config file in each of her apps so she can fire up
dance.pl in each of the apps, and have each one of them listen on
different ports. Perhaps something like this

    app0 at http://localhost:3000/
    app1 at http://localhost:3001/
    app2 at http://localhost:3002/

Our developer wants to continue to serve some of her Apache apps as
they are, but also experiment with a few new apps with Dancer, but
access them without having to specify the different port numbers. The
easiest way to accomplish this is via the Apache module mod_proxy.

First, she enables mod_proxy in her httpd.conf. This is done by
uncommenting the following lines in httpd.conf

    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_http_module modules/mod_proxy_http.so

If she is unlucky enough to not have the above modules available, then
these modules will have to be compiled. Compiling mod_proxy and
mod_proxy_http is out of the scope of this document.

Now, she has to add the following proxy commands to httpd.conf

    ProxyRequests Off

    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>

    ProxyPass /app0/ http://localhost:3000/
    ProxyPassReverse /app0/ http://localhost:3000/
    ProxyPass /app1/ http://localhost:3001/
    ProxyPassReverse /app1/ http://localhost:3001/
    ProxyPass /app2/ http://localhost:3002/
    ProxyPassReverse /app2/ http://localhost:3002/

The above command instruct Apache to take the listed URIs at
http://localhost/ and query them on their respective ports. This
allows our developer to point the browser to http://localhost/app0/,
and actually get a response back from http://localhost:3000/

However, the above is not enough, because trying to get something from
http://localhost/app0 will fail (notice the lack of the trailing
slash). To make sure that http://localhost/app0 also work, another
Apache module called mod_rewrite is required using the following
commands in httpd.conf

    RewriteEngine on
    RewriteRule ^/app0$ app0/ [R]
    RewriteRule ^/app1$ app1/ [R]
    RewriteRule ^/app2$ app2/ [R]

Restart Apache, fire up dance.pl under each of the different app
directories, each listening on different ports, and enjoy the dances.

A few important notes: Since the new Dancer-powered websites are not
going to be served by Apache, they really shouldn't be kept under the
~/Sites path, because that is being served automatically by Apache by
virtue of being Apache's DocumentRoot. It is ok to locate the dances
under some other hierarchy outside of Apache's reach. I have mine
under ~/Dances

    ~/Dances/app0
    ~/Dances/app1
    ~/Dances/app2

The new websites might mix resources, perhaps getting some JavaScript
framework files being served from other computers, or perhaps even
from a traditional Apache website at http://localhost/lib, but also
have resources local to the apps under their own 'public' directories
(Dancer allows browsers to access resources under the 'public'
directory). This can be accomplished by having HTML in main.tt like so

    <!-- app specific resources -->
    <link rel="shortcut icon" href="favicon.ico" />
    <link type="text/css" rel="stylesheet" href="css/styles.css" />

    <!-- resources from lib -->
    <script type="text/javascript"
        src="/lib/jquery/jquery-1.4.min.js"></script>
    <link type="text/css" rel="stylesheet"
        href="/lib/SyntaxHighlighter/Styles/shCore.css" />
    <script type="text/javascript"
        src="/lib/SyntaxHighlighter/Scripts/shCore.js"></script>

Final note: Once everything is working, the apps will be moved to the
production server. The production server will not be serving stuff
from http://localhost, but will have a real DNS name. This will be
accomplished using VirtualHosts under Apache, whereby one can serve
multiple websites from the same server. Dancer can continue to
function as above, but the proxy commands will have to be moved to
respective VirtualHosts sections. That story is for another time.

-- 
Puneet Kishor http://www.punkish.org
Carbon Model http://carbonmodel.org
Charter Member, Open Source Geospatial Foundation http://www.osgeo.org
Science Commons Fellow, http://sciencecommons.org/about/whoweare/kishor
Nelson Institute, UW-Madison http://www.nelson.wisc.edu
-----------------------------------------------------------------------
Assertions are politics; backing up assertions with evidence is science
=======================================================================