Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Emplacken(3)	      User Contributed Perl Documentation	  Emplacken(3)

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:

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

perl v5.32.0			  2010-12-20			  Emplacken(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | COMMAND LINE OPTIONS | CONFIG FILES | DONATIONS | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Emplacken&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help