Jan Henning Thorsen > Toadfarm-0.45 > Toadfarm::Manual::Config

Download:
Toadfarm-0.45.tar.gz

Annotate this POD

Website

View/Report Bugs
Source  

NAME ^

Toadfarm::Manual::Config - Config file format for Toadfarm

DESCRIPTION ^

This manual gives in-depth information about the config file format.

Basics

The basic structure is a pure Perl file, which defines a hash-ref:

  {
    apps => [],
    hynotoad => {},
    log => {},
    paths => {},
    plugins => [],
    secrets => [],
  };

Anything you put before the hash-ref is up to you.

Apps

The "apps" key holds a list of application/config pairs. The application can either be a full path to the application or a class name. The config is either HTTP headers to trigger on, or "Special fields".

The apps are processed in the order they are defined. This means that the first app that match a given rule will receive the request.

The config example below contain all the special fields that you can use and a list of example headers to filter on. Each key (except "config") is used to filter the incoming request, and ALL the specified values must match for the request to get passed on to a given application.

  {
    apps => {
      "/path/to/myproject/script/myapp" => {

        # special fields
        config => { some_key => "value" },
        local_port => 8080,
        mount_point => "/myapp",
        remote_address => "127.0.0.1",

        # headers
        "Host" => "home.thorsen.pm",
        "User-Agent" => qr{curl},
        "X-Request-Base" => "http://home.thorsen.pm/whatever",
      },
      "Other::App" => {
        # ...
      },
      # ...
    },
    # ...
  };

Example HTTP request that will get sent to "myapp":

  -- Connect (http:home.thorsen.pm:8080)
  -- Client >>> Server (http://home.thorsen.pm/myapp)
  GET /myapp HTTP/1.1
  Connection: keep-alive
  Content-Length: 0
  Accept-Encoding: gzip
  Host: home.thorsen.pm
  User-Agent: curl/7.32.0
  X-Request-Base: http://home.thorsen.pm/whatever

So if "User-Agent" is "Mojolicious (Perl)" instead, but all the other headers match, then the request will NOT be passed on to "myapp".

Got difficulties getting a request through to an application? Try removing rules until the request gets through.

Special fields

Fields that are defined in the list below are special fields.

Additional fields might be added, but they will always be in lower case.

Hypnotoad

  {
    hypnotoad => {
      workers => 7,
      listen => ['http://*:8080'],
    },
  }

See "SETTINGS" in Mojo::Server::Hypnotoad for more options.

Log

It is possible to get Toadfarm to log for all your apps:

  {
    log => {
      file => '/path/to/log/file.log',
      level => 'debug', # debug, info, warn, ...
      combined => 1,
    },
  }

The trick here is the "combined" flag. It makes all the apps share the same Mojo::Log object.

Paths

You can specify custom template and public file paths for Toadfarm. This is useful if you want your own error templates or serve other assets from Toadfarm.

  {
    paths => {
      renderer => [ '/my/custom/template/path' ],
      static => [ '/my/custom/static/path' ],
    },
  };

Plugins

It is possible to load plugins into the core of Toadfarm.

  {
    plugins => [
      "Some::Plugin" => @config_arguments,
    ],
  };

Toadfarm comes with two plugins: Toadfarm::Plugin::AccessLog and Toadfarm::Plugin::Reload, but you can also use other plugins from CPAN.

Secrets

Specifying secrets for your app is really important if you are using sesssion.

  {
    secrets => ['my super secret'],
  }

See also "secrets" in Mojolicious.

AUTHOR ^

Jan Henning Thorsen - jhthorsen@cpan.org

syntax highlighting: