=head1 NAME

Test::BrewBuild::Tutorial - Basic overview of using the client/server aspects
of the Test::BrewBuild build system

=head1 DESCRIPTION

This document gives a basic overview of setting up remote test servers,
and how to dispatch build requests to them.

=head1 BEFORE YOU BEGIN

Read through the
L<brewbuild|https://metacpan.org/pod/distribution/Test-BrewBuild/bin/brewbuild> 
documentation so you know how the actual tester works.

You'll need:

<ul>
<li>Git, on both the dispatcher and all testers</li>
<li>to be using an Administrative user (Windows only)</li>
<li>your module accessible via a Git repository</li>
<li>the dispatch and all tester servers configured, see L<SERVER CONFIGURATION>
</ul>

=head1 SERVER CONFIGURATION

Recommended initial platform configuration guide:
L<Test Platform Configuration|https://metacpan.org/pod/distribution/Test-BrewBuild/bin/brewbuild#TEST-PLATFORM-CONFIGURATION>.

This applies to all C<Test::BrewBuild> systems, whether they'll be stand-alone,
a dispatcher or a tester.

=head1 SCENARIO

You've got a Linux box at C<10.1.1.1> with all IP addresses and ports bound on
the server available for listening on.

You've also got a Windows server on C<172.16.1.1>, but our
default port C<TCP 7800> is not available, which can only listen on that
specific IP address.

You will be dispatching from a FreeBSD server, so you also want to run a tester
on the C<localhost>.

On the dispatcher, we'll be located within a Git repository directory, so we'll
let the system take care of the repo management so we don't have to continuously
specify it.

See L<SEE ALSO> for more elaborate uses, command-line options of each script,
and details of the optional configuration file.

=head1 STEP 1: CONFIGURE TESTERS

=head2 Linux (10.1.1.1)

Since we can listen on all IPs and the default port is available for use, this
simple command will start the tester, and put it into the background:

    bbtester start

=head2 Windows (172.16.1.1)

On this server, we're not permitted to listen on all IP addresses, and since
port C<7800> is unavailable, we have to specify an alternate.

    bbtester start -i 172.16.1.1 -p 9999

=head2 localhost

Since this tester is the dispatching server, we don't want it listening on
public-facing IP addresses, so we'll specify just the local loopback:

    bbtester start -i 127.0.0.1

=head1 STEP 2: CONFIGURE DISPATCHER

=head2 COMMAND LINE BASIC RUN

By default, we dispatch the most basic build, by sending C<brewbuild> as the
test command. The following will dispatch a build to all three testers we
configured above, and then wait for them to return the results.

    bbdispatch -t 127.0.0.1, 172.16.1.1:9999, 10.1.1.1

To specify a different command string:

    bbdispatch -c brewbuild -r -R -d 7 -t 127.0.0.1, 172.16.1.1:9999, 10.1.1.1

To specify a different repository:

    bbdispatch -r https://github.com/user/repo -t 127.0.0.1, 172.16.1.1:9999, 10.1.1.1

=head2 CONFIGURATION FILE RUN

In your configuration file, you can set up all of your testers, along with the
preferred command string (and repository if need be):

    [dispatch]
    cmd = brewbuild -R -d 7
    testers = 127.0.0.1, 172.16.1.1:9999, 10.1.1.1

Then your dispatch run can be initiated simply by:

    bbdispatch

=head1 TROUBLESHOOTING

If your dispatcher doesn't seem to be doing the right thing, you can enable
debug logging, which will print directly to C<STDOUT>:

    bbdispatch [...] -d 7

If your testers don't seem to be behaving properly, first, log into the remote
server and stop the currently running tester:

    bbtester stop

Restarting the tester in daemon mode with a debug level will include its logging
in the return to the dispatcher:

    bbtester start -d 7

You can also run the tester in the foreground, and get its logging displayed to
C<STDOUT> live-time:

    bbtester --fg -d 7 --stdout

If you want to get the debugging information from the actual C<brewbuild>
process included in the tester debug results, call C<brewbuild> from the
dispatcher with debug flags enabled. These debug results will be either included
in the tester's return, or printed to its C<STDOUT>, depending on how you're
debugging the tester:

    bbdispatch [...] -c brewbuild -d 7

Using the L<Test::BrewBuild::Dispatch> API, you can enclose all debug output and
return values into one scalar variable, and either dump it to a file or examine
it all in one location:

    use Capture::Tiny qw(capture_stdout);
    use Test::BrewBuild::Dispatch;

    my $return;

    my $stdout = capture_stdout {
        my $d = Test::BrewBuild::Dispatch->new(debug => 7);

        $return = $d->dispatch(
            cmd     => 'brewbuild -d 7',
            repo    => 'https://stevieb9@github.com/stevieb9/mock-sub',
            testers => [ qw(10.1.1.1) ],
        );
    };

    $return .= $stdout;

    print $return;

=head1 QUICK START

Quick start basic example, with one remote tester.

Tester 10.1.1.1:

    bbtester start

Dispatcher:

    bbdispatch -t 10.1.1.1

=head1 SEE ALSO

Details on the configuration file: L<Test::BrewBuild::brewbuild.conf>.

Dispatch script usage information:
L<bbdispatch|https://metacpan.org/pod/distribution/Test-BrewBuild/bin/bbdispatch>.

Tester script usage information:
L<bbtester|https://metacpan.org/pod/distribution/Test-BrewBuild/bin/bbtester>.




