/ 
Emplacken-0.01
/ Emplacken

NAME

Emplacken - Manage multiple plack apps with a directory of config files

VERSION

version 0.01

SYNOPSIS

emplacken --dir /etc/emplacken start

emplacken --dir /etc/emplacken stop

DESCRIPTION

NOTE: This is all still experimental. Things may change in the future.

Emplacken is a tool for managing a set of Plack applications based on config files. It also adds support for privilege dropping and error logs to those Plack servers that don't support these features natively.

It works be reading a config file and using that to generate a PSGI application file based on your config. It knows how to generate Catalyst, Mojo, and Mason app files natively. For other apps, or more complicated setups, you can supply a template to Emplacken and it will use that to generate the PSGI app.

COMMAND LINE OPTIONS

The emplacken command accepts either a --dir or --file option. If you don't specify either, it defaults to using the /etc/emplacken directory.

You must also pass a command, one of start, stop, restart, or status.

Finally, you can specify a --verbose or --no-verbose flag. This determines whether the start and stop command print to stdout. The status command always prints to stdout.

CONFIG FILES

This module uses Config::Any to read config files, so you have a number of choices for config file syntax. These examples will use either INI or JSON syntax.

All the config options should be in a single top-level section.

Common Config Options

These options are shared for all servers and code builders.

For config file styles that don't support multiple values for a single option, you can use a comma-separated string to set multiple options.

server

This will be passed to the plackup command to tell it what server class to use, for example Starlet or Corona. If you specify Starman, then the starman command will be used instead of plackup.

You can also use the value "plackup" here, which will let the Plack code pick the server automagically.

This is required.

builder

The code builder to use. Currently, this can be one of Catalyst, Mason, Mojo, or FromTemplate. Each code builder support different config options. See below for details.

pid_file

The location of the pid file for this application.

This is required.

include

A set of include directories to be passed to plackup. You can specify multiple values.

modules

A set of modules to be passed to plackup. You can specify multiple values. These modules will be preloaded by plackup.

listen

This can be "HOST", "HOST:PORT", ":PORT", or a path for a Unix socket. This can be set multiple times, but some servers may not support multiple values.

user

If this is set then Emplacken will attempt to become this user before starting the PSGI app.

group

If this is set then Emplacken will attempt to become this group before starting the PSGI app.

middleware

This can be one or more middleware modules that should be enabled. Note that there is no way to pass config options to these modules (yet?). You can specify multiple values.

reverse_proxy

If this is true, then the Plack::Middleware::ReverseProxy module is enabled for requests coming from 127.0.0.1.

access_log

If this is set to a file, then the Plack::Middleware::AccessLog module is enabled. It will log to the specified file.

access_log_format

This can be used to change the access log format.

error_log

If this is set, then the generated PSGI app will tie STDERR and log to a file. The log format is like Apache's error log, so you'll get something like this:

[Sun Dec 19 00:42:32 2010] [error] [client 1.2.3.4] Some error

Any error output from Perl will be tweaked so that it fits on a single line. All non-printable characters will be replaced by their hex value.

Starman Options

If you are using the Starman server, there are several more options you can set in the config file.

workers

The number of worker processes to spawn.

backlog

The maximum number of backlogged listener sockets allowed.

max_requests

The maximum number of requests per child.

preload_app

If this is true, then your PSGI app is preloaded by Starman before any child processes are forked.

disable_keepalive

If this is true, then keepalive is disabled.

Catalyst Options

If you are using the Catalyst code builder, you must specify an app_class config option. This is the name of the class for your web application.

Mason Options

If you are using the Mason code builder, you must specify comp_root and data_dir config options.

Mojo Options

If you are using the Mojo code builder, you must specify an app_class config option. This is the name of the class for your web application.

FromTemplate

If you are using the FromTemplate code builder, you must specify a template config option. This should be the file which contains the PSGI app template to use.

Template Variables

You can provide your own Text::Template template file for Emplacken to use as a template when building the PSGI application file. The builder will set the code delimeters to {{ and }}.

You should design your template to expect several variables:

  • {{$modules}}

    This will be a set of use statements loading any needed modules. This will include modules specified in the modules config key, and well as additional modules Emplacken may require in your PSGI application file.

  • {{$pre}}

    This will be a chunk of code that should come before any setup code you need to write, and before the builder block.

  • {{$builder_pre}}

    This should go immediately inside your builder block.

  • {{$mw}}

    This will be a chunk of code that enables middleware. It will include middleware specified by the middleware config option as well as anything else Emplacken needs (like the access log code).

  • {{$post}}

    This will be a chunk of code that should come after the builder block at the end of the file.

Here is an example template for a Catalyst application called MyApp:

use strict;
use warnings;

use MyApp;
{{$modules}}
{{$pre}}

MyApp->setup_engine('PSGI');

builder {
    {{ $builder_pre }}
    {{ $mw }}
    sub { MyApp->run(@_) };
};

{{$post}}

DONATIONS

If you'd like to thank me for the work I've done on this module, please consider making a "donation" to me via PayPal. I spend a lot of free time creating free software, and would appreciate any support you'd care to offer.

Please note that I am not suggesting that you must do this in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me.

Similarly, a donation made in this way will probably not make me work on this software much more, unless I get so many donations that I can consider working on free software full time, which seems unlikely at best.

To donate, log into PayPal and send money to autarch@urth.org or use the button on this page: http://www.urth.org/~autarch/fs-donation.html

BUGS

Please report any bugs or feature requests to bug-emplacken@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2010 by Dave Rolsky.

This is free software, licensed under:

The Artistic License 2.0