=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
L<GitHub|https://github.com/ollyg/netdisco-frontend-sandpit/tarball/master>
and extract it on your system. Make sure the system has access to your
Netdisco database.

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>).

=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.

Below is a complete list of the Perl library dependencies, but to avoid
muddying your system, use the following shell script to download and install
them into a custom library path:

 mkdir -p ~/perl-profiles/netdisco-web
 curl -L http://cpanmin.us/ | perl - --notest --quiet --local-lib-contained "~/perl-profiles/netdisco-web" \
     App::cpanminus \
     App::local::lib::helper \
     Dancer \
     DBIx::Class \
     Dancer::Plugin::DBIC \
     NetAddr::IP \
     Net::MAC \
     List::MoreUtils \
     Net::DNS \
     Socket6 \
     HTML::Entities \
     Template::Toolkit

Then initialiaze an environment with access to these modules (for the lifetime
of the shell):

 ~/perl-profiles/netdisco-web/bin/localenv

=head1 STARTUP

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

 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.

If you've patched your C<node_ip> table to have a cached DNS entry column
called C<dns> then uncomment the two indicated lines in C<NodeIP.pm>.

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

=head1 RATIONALE

The interface is written using Twitter's Bootstrap CSS library. This makes it
very easy to achieve a decent look and feel. Additional functionality is
provided by a few JQuery plugins.

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.

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.

=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.