=head1 NAME

Toadfarm::Manual::Intro - Introduction to Toadfarm

=head1 DESCRIPTION

This manual aims to give an introduction to how to set up C<toadfarm>.

=head2 Config

First you need to create a configuration file to describe when an application
will be triggered. The config file is in plain Perl format and need to
contain a list of application you want to run and a set of HTTP headers to
trigger a given application.

Example:

  {
    apps => [
      '/home/web/project1/script/app1' => {
        'X-Request-Base' => 'http://mydomain.com/whatever',
      },
      '/home/web/project2/script/app2' => {
        'Host' => 'mydomain.com',
      },
    ],
  }

The config above will pass the request on to C<app1> when the
"X-Request-Base" header is set to "http://mydomain.com/whatever".
Or it will pass the request on to C<app2> if the "Host" header is
set to "mydomain.com".

You can save the content of the file anywhere, but the suggested location is
C<$HOME/.toadfarm/toadfarm.conf>.

Note: There are other special fields to trigger on, besides HTTP headers. See
L<Toadfarm::Manual::Config/Apps> for more details.

=head2 Start Toadfarm

After you have saved the config file, you can start L<Toadfarm>:

  $ toadfarm $HOME/.toadfarm/toadfarm.conf

After this, you should see C<toadfarm> running and the applications can be
accessed from "http://yourdomain.com:8080".

=head2 Further reading

See L<Toadfarm::Manual::RunningToadfarm> for more command line options, and
L<Toadfarm::Manual::Config> for full list of config file options.

=head2 Listen to standard ports

Setting up an iptables rules will allow Toadfarm to listen to port 8080, while
still receiving traffic on the default port. This is a good idea security wise,
since it will not require Toadfarm to be started as "root".

  $ iptables -A PREROUTING -i eth0 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 8080
  $ iptables -A PREROUTING -i eth0 -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 8443

Note: You need to replace "eth0" with the appropriate interface.

=head1 SEE ALSO

L<Toadfarm::Manual::Config>.

L<Toadfarm::Manual::RunningToadfarm>.

=head1 AUTHOR

Jan Henning Thorsen - C<jhthorsen@cpan.org>

=cut
