=head1 INTRODUCTION

The content of this distribution is a the next major version of 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

Clone the git repository:

 git clone git://netdisco.git.sourceforge.net/gitroot/netdisco/netdisco-2

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, or
simply want to use Netdisco without logging in. 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

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 \
     SQL::Translator \
     Dancer::Plugin::DBIC \
     Daemon::Generic \
     Config::Tiny \
     SNMP::Info \
     NetAddr::IP \
     Net::MAC \
     namespace::clean \
     Role::Tiny \
     List::MoreUtils \
     Socket6 \
     HTTP::Tiny \
     HTML::Entities \
     Template::Toolkit \
     YAML

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

B<Note> You also need to install L<DBD::Pg>. Best advice is 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

=head2 Database Update

You will need the latest Netdisco DB schema in your PostgreSQL server. Most
important is to have a C<dns> column in your C<node_ip> table. This
distribution includes scripts which can upgrade the DB schema for you, but
B<please> do take backups beforehand!

Whether you have no existing DB schema, or an existing DB schema without the
latest updates, simply run the following script in this distribution:

 bin/upgrade_netdisco_schema_version

The script should detect what needs to be done in your database and apply the
necessary changes. It will also add a table to keep track of what's changed,
so that you can run the script again in the future and receive more updates.

You can even run this script on a virgin, empty database. Make sure there is a
database created for Netdisco (C<createdb>) and a PostgreSQL user who has
rights to create tables in the databse (C<createuser>). Configure the
C<Netdisco/environments/development.yml> file then run this script.

=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

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

=head1 FUTURE WORK

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. Helper functions
and canned searches have been added to support the web interface.

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