La séptima vida

...o el gato así lo espera/teme

Deploying Kelp applications in a shared host

Executing your site from a shared host means that you rent a space in a web server which handles many other sites and domanins in addition to yours. Performance is usually not great, you normally cannot run processes with long duration, and your shared host will certainly not scale if you are building the next Facebook. Usually, the web server will be Apache, and your control over server configuration is limited to .htaccess files. You may have MySQL, some times not PostgreSQL, and you may not have the freedom to go crazy with database creation. In addition to that, you are likely constrained to using CGI, the Common Gateway Interface, which launches a new process and the Perl interpreter for each hit your application gets. And yes, the proposed Perl version is very likely quite old. Hopefully 5.10, but you should check as it may be worst.

Looking at the positive side, you are freed from the actual administration of the server; even if it is old, you are very likely to have Perl by default, and shared hosting is among the least expensive ways of publishing your application. Shared hosting remains a good option for small applications with low usage.

Running a Kelp application in a shared host is possible, because Plack offers support for CGI. Server configuration boils down to the use of mod_rewrite, an Apache module that we will use to route URL requests to your application, and .htaccess files. In addition to that, you will need a dispatching CGI script because plackup is not usually available to the web server. It will probably be available to you, but it is not available for Apache.

Uploading your application

The default layout of Kelp is retained, but public-facing files must be stored within the server root. To upload the application, the following steps were needed:

  • Install all of your application dependencies. This can be done using cPanel or perhaps you have SSH access to your account and lib::local installed.
  • Upload all the static, public-facing files and directories to the public_html (well, within your server's root) directory. This includes all of the CSS files, JavaScript libraries, images, and fonts.
  • Outside of the server root, create a directory and upload the important files of your application:
    • your app.psgi file
    • the lib/ directory
    • the conf/ directory
    • the log/ directory
    • create a sessions directory if needed
    • and your views/ directory.
    Note that log and sessions need to be writable by the web server.
  • In a directory where CGI scripts are allowed, create a dispatch script like the one described below.
  • Because we need Kelp to look for its files relative to the app.psgi file and not relative to the dispatch script, modify the .psgi file to chdir to the application directory instead.
  • Fight a little with the .htaccess configuration file for Apache, so that it will redirect your routes to your dispatch script. The location for this file is your server's root directory.

The dispatch script

In your local machine and probably even in your shared host, you can use plackup to run your application. This program will detect that your script is running as a CGI, so if it is available to the web server, you can go ahead and simply use it by including the following shebang (see Plack::Handler::CGI):

#! /usr/bin/env plackup

However, plackup is not likely to be be available to the server. The job of the dispatch script is to use Plack::Loader to load your .psgi file and run your app. The following script will do it:

#!/usr/bin/env perl

use lib '/path/to/your/local/lib';
use Plack::Loader;

my $app = Plack::Util::load_psgi("/path/to/your/app.psgi");
Plack::Loader->auto->run($app);

Remember that you can use Find::Bin to avoid hard coding your paths, and do not forget to make your script executable by the web server.

Redirecting requests to the dispatch script

Finally, HTTP requests must be re-directed to the CGI script above, which will execute your application. This redirection can be made with Apache's mod_rewrite within an .htaccess file. Supposing that the above CGI script is at /cgi-bin/dispatch.cgi, you could use:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ /cgi-bin/dispatch.cgi/$1 [QSA,L]

And that should be enough to get you started. Static files, which can be found by their normal URL, will be served by Apache. The dispatch script will be used only for files which are not found at their expected location within the file system, and that applies to your routes.

While this should get you started in a good path, I would not expect to get everything working correctly at the first try. You could use the development mode in your Kelp application to debug it, and you can also run the CGI script manually to see any missing dependency or other kind of errors.

Conclusion

The process of running a Kelp application in a shared host is not difficult, but you will have to work with configuration files, CGI scripts, and the particularities of your selected provider. But once it works... it works!