PLACKUP(1)

NAME
plackup - Run PSGI application with Plack servers

SYNOPSIS
  # read your app from app.psgi file
  plackup

  # can be passed as an ARGV[0] (or with -a option)
  plackup hello.psgi

  # Switch server implementation with --server (or -s)
  plackup --server HTTP::Server::Simple --port 9090 --host 127.0.0.1 test.psgi

  # Use UNIX socket to run FCGI daemon
  plackup -s FCGI --listen /tmp/fcgi.sock myapp.psgi

  # FCGI external server on port 9090
  plackup -s FCGI --port 9090

DESCRIPTION
plackup is a command line utility to run PSGI application from the command line.

plackup automatically figures out the environment it is run in, and runs your application in that environment. FastCGI, CGI, AnyEvent and others can all be detected. See Plack::Loader for the authorative list.

"plackup" assumes you have an "app.psgi" script in your current directory, that would look like:

  #!/usr/bin/perl
  use MyApp;
  my $application = MyApp->new;
  my $app = sub { $application->run_psgi(@_) };

The last statement of "app.psgi", in this case $app, should be a code reference that is a PSGI application.

ARGUMENTS

.psgi
      plackup --host 127.0.0.1 --port 9090 /path/to/app.psgi

    The first non-option argument is used as a ".psgi" file path. You can also set this path with "-a" or "--app" option. If omitted, the default file path is "app.psgi" in the current directory.

OPTIONS

-a, --app
    "--app" option allows you to locate a ".psgi" script with a different name in a different path. This can also be set as a non-option argument. (See above)

-e  Evaluate the given perl code as a PSGI app, much like perl's "-e" option.

      plackup -e 'sub { my $env = shift; return [ ... ] }'

    You can also specify "-e" option with ".psgi" file path to wrap the application with middleware configuration from the command line. You can also use Plack::Builder DSL syntax inside "-e" code.

      plackup -e 'enable "Auth::Basic", authenticator => ...;' myapp.psgi

    equals to run the following PSGI application:

      use Plack::Builder;
      use Plack::Util;

      builder {
          enable "Auth::Basic", authenticator => ...;
          Plack::Util::load_psgi("myapp.psgi");
      };

    Note that when you use "-e" option to enable middleware, plackup doesn't assume the implicit "app.psgi" path. You should always pass ".psgi" path in the command line arguments.

      plackup                             # Runs app.psgi
      plackup -e 'enable "Foo"'           # Doesn't work!
      plackup -e 'enable "Foo"' app.psgi  # Works

-o, --host
    The interface a TCP based server daemon binds to. Defauts to undef, which lets most server backends bind the any (*) interface. This option doesn't mean anything if the server does not support TCP socket.

-p, --port
    The port number a TCP based server daemon listens on. Defaults to 5000. This option doesn't mean anything if the server does not support TCP socket.

-s, --server
    Select a specific implementation to run on using the "PLACK_SERVER" environment variable or use the "-s" or "--server" flag which will be preferred over the environment variable if present.

    If this option is not given, plackup will try to detect the best server implementation based on the environment variables as well as modules loaded by your application in %INC. See Plack::Loader for details.

-S, --socket
    UNIX domain socket path to listen on. Defaults to undef. This option doesn't mean anything if the server doesn't support UNIX sockets.

-l, --listen
    Addresses to listen on. It could be "HOST:PORT", ":PORT" or "PATH" (without colons). It could be multiple but it depends on the server implementations whether multiple interfaces are supported.

-D, --daemonize
    Makes the process go background. It's up to the backend server/handler implementation whether this option is respected or not.

-I  Specify perl library include path, like "perl"'s -I option.

-M  Specify modules to load before loading the app code.

-E, --env
    Specify the environment option (default is "development"). You can set this value by setting "PLACK_ENV" environment variable as well, and specifying the value with the command line options writes back to "PLACK_ENV" as well, so applications or frameworks can tell which environment setting the application is running on.

      # These two are the same
      plackup -E deployment
      env PLACK_ENV=deployment plackup

    The value can be anything but commonly used ones are "development", "deployment" and "test".

    If it's set to "development", following middleware components are enabled by default: AccessLog, StackTrace and Lint.

-r, --reload
    Make plackup to watch updates from your development directory and restarts the server whenever a file is updated. This option by default watches the "lib" directory and the base directory where .psgi file is located. Use "-R" if you want to watch other directories.

    Because "-r" option (or "-R", see below) will delay the compilation of your application, automatic server detection (See the explanation of "-s" above) depending on the modules used in your application will fail. You're recommended to explicitly specify "-s" in such cases.

-R, --Reload
    "-R" option allows you to specify the path to watch file updates separated by comma (",").

      plackup -R /path/to/project/lib,/path/to/project/templates

-L, --loader
    Specify the server loading subclass that implements how to run the server. Available options are Plack::Loader (default), Restarter (automatically set when "-r" or "-R" is used), Delayed and Shotgun.

    See Plack::Loader::Delayed and Plack::Loader::Shotgun when to use those loader types.

--access-log
    Specify the pathname of a file where the access log should be written. By default, in the development environment access logs will go to STDERR.

Other options that starts with "--" are passed through to the backend server. See each Plack::Handler backend documentations to see which options are available.

SEE ALSO
Plack::Runner Plack::Loader