=head1 INTRODUCTION

The content of this distribution is a new, experimental web frontend for the
Netdisco network management tool. See L<http://netdisco.org/> for further
information on the project.

If you have any trouble getting the frontend running, or it blows up in your
face, please contact C<oliver> in the C<#netdisco> IRC channel (on freenode).

=head1 INSTALLATION

Download the tarball from GitHub and extract it on your system. Make sure the
system has access to your Netdisco database.

 https://github.com/ollyg/netdisco-frontend-sandpit/tarball/master

Edit the C<Netdisco/environments/development.yml> file to have the correct
credentials and settings (host name) for your own Netdisco database.

In the same file, uncomment the C<no_auth> setting if you use Apache auth.
Currently the frontend only works with the built-in Netdisco authentication.

Optionally, in the same file uncomment and edit the C<domain_suffix> setting
to be appropriate for your local site (same as the C<domain> setting in
C<netdisco.conf>).

If you have a C<dns> column in your C<node_ip> table then set the 
C<have_nodeip_dns_col> option also. Note that this can also enable a "live"
DNS lookup but you probably don't want the performance hit.

=head2 Dependencies

You will need to have Netdisco itself installed on the system as this module
will try to load the C<netdisco.pm> library.

To avoid muddying your system, use the following shell script to download and
install Perl dependencies into a custom library path:

 curl -L http://cpanmin.us/ | perl - --notest --quiet --local-lib-contained "${HOME}/perl-profiles/netdisco-web" \
     App::cpanminus \
     App::local::lib::helper \
     Dancer \
     DBIx::Class \
     DBIx::Class::Helper::Row::SubClass \
     DBD::Pg \
     Dancer::Plugin::DBIC \
     NetAddr::IP \
     Net::MAC \
     List::MoreUtils \
     Net::DNS \
     Socket6 \
     HTML::Entities \
     Template::Toolkit \
     YAML

In case you were wondering, the vast majority of dependencies come from
L<DBIx::Class>.

B<Note> that to install L<DBD::Pg> you need the PostgreSQL development libraries
also installed. Best advice is to omit that item from the above script and try
to install a prebuilt DBD::Pg package for your OS. The following command will
test for the existence of DBD::Pg on your system:

 perl -MDBD::Pg\ 999

=head1 STARTUP

There's a simple web server built-in. This is sufficient for
standalone, single-user operation and development, but does not have
performance for a production environment.

The following command initializes an environment which can access the installed
Perl modules, then starts this small web server:

 ~/perl-profiles/netdisco-web/bin/localenv Netdisco/bin/netdisco-web.pl

Speak to C<oliver> on IRC if you want advice on firing up the application
under Apache, FastCGI, or other environments.

=head1 TIPS AND TRICKS

The main black navigation bar has a search box which is smart enough to work
out what you're looking for in most cases. For example device names, node IP
or MAC addreses, VLAN numbers, and so on.

Remember you can disable authentication by changing a setting in the
configuration file, as explained above.

For SQL debugging, and better performance, try the following command:

 DBIC_TRACE_PROFILE=console DBIC_TRACE=1 \
   plackup -R Netdisco/lib,Netdisco/public,Netdisco/views \
   Netdisco/bin/netdisco-web.pl

=head1 FUTURE WORK

At the moment the ability to just hit Enter in the title-bar Search is a
I<hack> because there's no other way to list all Inventory. When the Reports
code is added, the Inventory will be a part of that. It's understood that
simply hitting enter should return no results, not all results.

The intention is to support "plugins" for additonal features, most notably
columns in the Device Port listing, but also new menu items and tabs. The
design of this is sketched out but not implemented. The goal is to avoid
patching core code to add localizations or less widely used features. One
could imagine a C<Netdisco::Web::Plugin::> namespace for these.

Bundled with this app is a L<DBIx::Class> layer for the Netdisco database.
This could be a starting point for an "official" DBIC layer, but be warned
that at the moment it's a bit messy. Helper functions and canned searches have
been thrown together to support the web interface with little thought for
style or consistency or performance. That will come later.

=head1 CAVEATS

Some sections are not yet implemented, e.g. the Device Module tab.

Menu items on the main black navigation bar go nowhere, except Home.

None of the Reports yet exist (e.g. searching for wireless devices, or duplex
mismatches). These might be implemented as a plugin bundle.

The Wireless, IP Phone and NetBIOS Node properies are not yet shown.

When running the standalone built-in web server, it will occasionally
start to die on you. This usually manifests as returning page content
but no stylesheet. Restarting the server is the best solution.

=head1 COPYRIGHT AND LICENCE

 Copyright (c) 2012, The Netdisco Developer Team.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
     * Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
     * Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
     * Neither the name of the Netdisco Project nor the
       names of its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL THE NETDISCO DEVELOPER TEAM BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.