GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Emplacken(3) User Contributed Perl Documentation Emplacken(3)

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

version 0.01

  emplacken --dir /etc/emplacken start

  emplacken --dir /etc/emplacken stop

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.

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.

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.

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.

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.

If you are using the Mason code builder, you must specify "comp_root" and "data_dir" config 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.

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}}

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>

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.

Dave Rolsky <autarch@urth.org>

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

This is free software, licensed under:

  The Artistic License 2.0
2010-12-20 perl v5.32.1

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

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