Dreamhost
Dreamhost is a popular web hosting company that provides various services related to hosting websites, either with private servers or shared hosts.
Here we address the installation of a Mojolicious application - Mojolicious::Lite to be more precise - using FastCGI on a Dreamhost shared host without any privileged access (such as root password or sudo).
The first step to install a web application on Dreamhost is create a user account with shell access, and a domain pointing to some directory of that account.
Multiple applications and multiple domains can be configured under the same user account, but in this example we will use both an new account and a new domain to show all steps in detail.
A new user can be created through the administrative panel of Dreamhost.
Under Type of User Account we tick Shell: Allows SFTP/FTP plus shell access. This will allow that new user to access the server via ssh.
This is optional, but we also select the option Enhanced security to leave this account completely isolated, so none of our other user accounts can access the files under this account.
A domain or subdomain can also be configured via the control panel of Dreamhost.
In this tutorial we'll use a sub-domain, but it could be any other domain.
In the option Domain to host, we add the name of the sub-domain that will run the Mojolicious application. In our case, test.blabos.org.
In the option Do you want the www in your URL? we choose Remove WWW. This is a personal choice, it doesn't really matter to the process.
In the option PHP mode we select PHP 5 FastCGI. This is really important, as it enables FastCGI support into the directory that our sub-domain points to.
NOTE: In the Dreamhost wiki they warn users that, unfortunately, they only support FastCGI with PHP. Since we're using FastCGI with Perl, we're on our own. But then again, that's why you're reading this, right? :)
Under the Web directory option you may configure the directory that better suits your needs. This directory is where the sub-domain will point to and where we will install our Mojolicious application later.
The DNS update should take a few hours, so make sure to set both the user and the domain in advance (a day or two, for example).
After the updates take effect, you will be able to log into the sub-domain via ssh and access it (the directory configured above) via a browser. Yay!
Now it's time to setup local::lib, so we are able to install Perl modules from http://cpan.org directly into the home directory of our regular user. If you don't know how to do that, here's a crash-course:
1. Log into the server with you new user
2. Install cpanm. This really helps installation under Dreamhost, as the plain "cpan" can be quite heavy in terms of memory/cpu usage, leading Dreamhost's bots to kill it right in the middle of an installation.
[server]$ curl -L http://cpanmin.us | perl - App::cpanminusAfter that command, cpanm will be installed under $HOME/perl5/bin, but your $PATH and local::lib environment is not set yet.
3. Install local::lib
[server]$ $HOME/perl5/bin/cpanm local::libthen add this to your $HOME/.bash_profile file, so local::lib sets up all the required environment variables for local module installation:
[server]$ echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bash_profileNOTE: Usually we add the line above to .bashrc, but for Dreamhost, .bash_profile is what we're aiming for.
4. Start your local::lib environment! Now that we've setup our .bash_profile file, we can just log out and log back in, or simply call it again, like so:
[server]$ . ~/.bash_profileNOTE: the command above is a dot, then a space, then ~/.bash_profile.
After configuring the local::lib module we install Mojolicious with the command:
[server]$ cpanm MojoliciousMojolicious just depends on Perl's core modules, so the installation should be pretty fast.
Since version 1.98, Mojolicious has no native FastCGI support anymore, so we have to install the FastCGI server separately.
[server]$ cpanm Mojo::Server::FastCGISee Installation of FastCGI for more information.
After this we will create our own little test application within the directory which the sub-domain points to. In our case, it's test.blabos.org:
[server]$ cd test.blabos.org
[server]$ ls
favicon.gif quickstart.html favicon.ico
[server]$ mkdir TestApp
[server]$ cd TestApp
[server]$ vi app.pl Let's create our test application containing only the lines:
#!/usr/bin/env perl
use Mojolicious::Lite;
get '/' => sub {
my $self = shift;
$self->stash( message => 'Hello Dreamhost!' );
} => 'index';
app->start;
__DATA__
@@ index.html.ep
<html><body>
<center><h1><%= $message %></h1></center>
</body></html>NOTE: This is our test application. You could either use this, write your own, or just create a new application from the standard templates via the command mojo generate lite_app app.pl on your shell.
Now we need to give permission to execute it:
[server]$ chmod +x app.plWe can test out Mojolicious application by typing:
[server]$ ./app.pl cgiThis will output the rendered content right on the terminal and let you make sure the app is ok.
We could also test it using Mojolicious' internal web server:
[server]$ ./app.pl daemon
Sat Sep 11 19:56:19 2010 info Mojo::Server::Daemon:363 [17141]: Server
listening (http://*:3000)
Server available at http://*:3000.And point our browser to http://server.dreamhost.com:3000 (where server.dreamhost.com is the DreamHost server where you logged in, NOT your application's domain name).
You should note, however, that running daemons in your DreamHost shared account might conflict with Dreamhost's policy, so you're advised against it.
We keep this information here as it might be useful for those with a dedicated account.
At this point we only guaranteed that our application does not contain syntax errors and it is fully functional. We still need to configure the FastCGI environment.
Because of Dreamhost's process management policy on the shared server, the script executable application MUST be renamed from app.pl to dispatch.fcgi:
[server]$ mv app.pl dispatch.fcgiThe application also needs to get explicit paths to the modules that were installed in the user directory. This means we need to add a couple of new lines in our application:
#!/usr/bin/env perl
use lib '/home/user/perl5/lib/perl5'; # [new] replace "user" with your username
use local::lib; # [new]
# the rest of the application remains the same
use Mojolicious::Lite;
get '/' => sub {
my $self = shift;
$self->stash( message => 'Hello Dreamhost!' );
} => 'index';
app->start;
__DATA__
@@ index.html.ep
<html><body>
<center><h1><%= $message %></h1></center>
</body></html>Another detail documented in the Dreamhost wiki is that both your dispatch.fcgi application and the directory where it lies need to belong to the same user and group account you created. In addition, both must have write permission enabled for the whole group.
In our tests this configuration was irrelevant, but since it's documented, let's keep it:
[server]$ chmod -R g+w TestApp/Our directory structure from the root directory of the sub-domain should now be something like:
[server]$ tree -a
.
|-- .htaccess
|-- TestApp
| `-- dispatch.fcgi
|-- favicon.gif
|-- favicon.ico
`-- quickstart.htmlThe files favicon.gif, favicon.ico and quickstart.html are installed by Dreamhost when creating the sub domain and have absolutely nothing to do with our application.
To configure the FastCGI environment, we need to create a file called .htaccess in the directory pointed to by our sub-domain (in our case, test.blabos.org). This file allows us to pass custom settings to Dreamhost's web server (Apache) that apply only to our application (that directory tree) and without requiring any administrative access. For details about .htaccess files, see the Apache documentation.
Now begins the tricky part :)
According to the FastCGI documentation in the Dreamhost wiki, our .htaccess file must have the content below:
Options +FollowSymLinks +ExecCGI
AddHandler fastcgi-script .fcgi
RewriteEngine On
RewriteRule ^(.*)$ TestApp/dispatch.fcgi [QSA,L]NOTE: Remember, our application is under $HOME/test.blabos.org/TestApp. Replace "TestApp" above with whatever sub-directory you placed your application in.
Although this configuration allows our application startup, it is insufficient to ensure the correct functioning of Mojolicious routes. This may lead to a preliminary false sense of correctness since the application starts. As the complete configuration of mod_rewrite is also beyond the scope of this text, let's just say that the configuration that best behaved for us was:
Options +FollowSymLinks +ExecCGI
AddHandler fastcgi-script .fcgi
RewriteEngine On
RewriteRule ^(TestApp/dispatch\.fcgi/.*)$ - [L]
RewriteRule ^(.*)$ TestApp/dispatch.fcgi/$1 [QSA,PT,L]You may explore all other options of configuration, but remember to kill your application whenever you update the .htaccess file. Again, there's a catch. After you kill the process you MUST erase the session files at /tmp directory:
[server]$ killall -9 dispatch.fcgi && rm /tmp/sess_* -Rf > /dev/null 2>&1Missing this will most likely throw you into a deep pit of mess. Don't worry about removing other people's session files on /tmp, since your user won't have permission to do it. Or at least we hope so :)
Now the application should be working, and opening http://yourdomain should give you that nice and warm "Hello, Dreamhost!" message.
If you later decide to expand your Lite application to a full-blown Mojolicious app, remember that you need to touch dispatch.fcgi every time you want to restart it:
[server]$ touch dispatch.fcgiThat's it. Have fun!
Blabos de Blebe
Breno G. de Oliveira
This text is licensed under Creative Commons by-sa