App::Padadoy - Simply deploy PSGI applications
version 0.125
Create a new application and start it locally on your development machine:
$ padadoy create Your::Module $ plackup app/app.psgi
Start application locally as deamon with bundled dependencies:
$ padadoy cartontest $ padadoy start
Show status of your running application and stop it:
$ padadoy status $ padadoy stop
Manage your application files in a git repository:
$ git add * $ git commit -m "inial commit"
Deploy the application at dotCloud
$ dotcloud create nameoryourapp $ dotcloud push nameofyourapp
Prepare your own deployment machine (as remote in padadoy.yml):
remote
padadoy.yml
$ padadoy remote init
Add your deployment machine as git remote and deploy:
$ git remote add prod ... $ git push prod master
This is an early preview release, be warned! Design changes are likely, at least until a stable carton 1.0 has been released!
Padadoy is a command line application to facilitate deployment of PSGI applications, inspired by http://dotcloud.com. Padadoy is based on the Carton module dependency manager, Starman webserver, and git. In short, an application is managed in a git repository and pushed to a remote repository for deployment. At the remote server, required modules are installed and unit tests are run, to minimize the chance of a broken installation.
An application is managed in a git repository with following structure. You can create it automatically with padadoy create or padadoy create Your::App::Module.
padadoy create
padadoy create Your::App::Module
app/ app.psgi - application startup script lib/ - local perl modules (at least the actual application) t/ - unit tests Makefile.PL - used to determine required modules and to run tests deplist.txt - a list of perl modules required to run (o) data/ - persistent data (o) dotcloud.yml - basic configuration for dotCloud (o) libs -> app/lib - symlink for OpenShift (o) deplist.txt -> app/deplist.txt - symlink for OpenShift (o) perl/index.pl - CGI script for OpenShift (o)
This directory layout helps to easy deploy on multiple platforms. Files and directories marked by (o) are optional, depending on what platform you want to deploy. Padadoy also facilitates deploying to your own servers just like a PaaS provider.
(o)
On the deployment machine there is a directory with the following structure:
repository/ - the bare git repository that the app is pushed to current -> ... - symbolic link to the current working directory new -> ... - symbolic link to the new working directory on updates padadoy.yml - local configuration
You can create this layout with padadoy remote init. After adding the remote repository as git remote, you can simply deploy new versions with git push.
padadoy remote init
git push
Start padadoy, optionally with some configuration (padadoy.yml).
Create an application boilerplate.
List dependencies (not implemented yet).
Initialize on your deployment machine.
Show configuration values.
Start or gracefully restart the application if running.
Start starman webserver with carton.
Stop starman webserver.
Show some status information.
Check out a revision to a new working directory. If no directory name is specified, the revision name will be concatenated to the base directory. If a current directory is specified, the local directory will first be copied with rsync to avoid reinstallation of dependent packages with carton.
local
Update dependencies with carton and run tests.
Checkout a revision, test it, and create a symlink called new on success.
new
This method is called as post-receive hook in the deployment repository. It creates (or changes) the symlink new to the symlink current and restarts the application.
current
Run padadoy on a remote machine.
Consult logfiles.
Show version number and exit.
Actually, you don't require padadoy if you only deploy at some PaaS provider, but deployment at dotCloud and OpenShift is also documented below for convenience.
The following should work at least with a fresh Ubuntu installation and Perl >= 5.10. First you need to install git, a build toolchain, and cpanminus:
$ sudo apt-get install git-core build-essential lbssl-dev $ wget -O - http://cpanmin.us | sudo perl - --self-upgrade
Now you can install padadoy from CPAN:
$ sudo cpanm App::Padadoy
Depending on the Perl modules your application requires, you may need some additional packages, such as libexpat1-dev for XML. For instance for HTTPS you need LWP::Protocol::https that requires libnet-ssleay-perl to build:
libexpat1-dev
libnet-ssleay-perl
$ sudo apt-get install libnet-ssleay-perl $ sudo cpanm LWP::Protocol::https
For each deployment you create a remote repository and initialize it:
$ padadoy init
You may then edit the file padadoy.yml to adjust the port and other settings. Back on another machine you can simply push to the deployment repository with git push. padadoy init installs some hooks in the deployment repository so new code is first tested before activation.
padadoy init
In most cases, you will run your application begind a reverse proxy, so you should include Plack::Middleware::XForwardedFor to get real remote IPs.
Create a dotCloud account and install the command line client as documented at https://docloud.com.
Create an OpenShift account, install the command line client, and create a domain, as documented at https://openshift.redhat.com/app/getting_started (you may need to sudo apt-get install libopenssl-ruby, and to find and fiddle around the client at /var/lib/gems/1.8/bin/rhc to actually make use of it). Att your OpenShift repository as remote and merge.
sudo apt-get install libopenssl-ruby
/var/lib/gems/1.8/bin/rhc
The remote repository contains two git hooks, which are enabled by padadoy init: the update hook calls padadoy update with the revision hash that is pushed to the repository:
update
padadoy update
#!/bin/bash newrev="$3" padadoy update $newrev
On success, the post-receive hook calls padadoy enable to
post-receive
padadoy enable
There are many ways to deploy PSGI applications. See this presentation by Tatsuhiko Miyagawa for an overview:
http://www.slideshare.net/miyagawa/deploying-plack-web-applications-oscon-2011-8706659
By now, padadoy only supports Starman web server, but it might be easy to support more.
This should also work on Amazon EC2 but I have not tested yet. See for instance http://www.deepakg.com/prog/2011/01/deploying-a-perl-dancer-application-on-amazon-ec2/.
What does "padadoy" mean? The funny name was derived from "PlAck DAncer DeplOYment" but it does not mean anything.
Jakob Voss
This software is copyright (c) 2012 by Jakob Voss.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install App::Padadoy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Padadoy
CPAN shell
perl -MCPAN -e shell install App::Padadoy
For more information on module installation, please visit the detailed CPAN module installation guide.