Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  EMPLACKEN (3)

.ds Aq ’


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



version 0.01


  emplacken --dir /etc/emplacken start

  emplacken --dir /etc/emplacken stop


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

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.


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.


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.


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.


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.


The location of the pid file for this application.

This is required.


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


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


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.


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


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


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.


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


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


This can be used to change the access log format.


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] 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.


The number of worker processes to spawn.


The maximum number of backlogged listener sockets allowed.


The maximum number of requests per child.


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


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.


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:
o {{$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.

o {{$pre}}

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

o {{$builder_pre}}

This should go immediately inside your builder block.

o {{$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).

o {{$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;


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



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 <B>I am not suggesting that you must do thisB> 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 or use the button on this page: <>


Please report any bugs or feature requests to, or through the web interface at <>. I will be notified, and then you’ll automatically be notified of progress on your bug as I make changes.


Dave Rolsky <>


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

This is free software, licensed under:

  The Artistic License 2.0

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 EMPLACKEN (3) 2010-12-20

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.