update README and main module POD

Netdisco/lib/App/Netdisco.pm

@@ -24,9 +24,107 @@ BEGIN {
   }
 }
 
-=head1 App::Netdisco
+=head1 NAME
 
-Netdisco is an Open Source web-based network management tool.
+App::Netdisco - An open source web-based network management tool.
+
+=head1 Introduction
+
+The contents of this distribution is 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 speak to someone in the C<#netdisco> IRC channel (on freenode).
+
+=head1 Installation
+
+Netdisco has several Perl library dependencies which will be automatically
+installed. However it's I<strongly> recommended that you first install
+L<DBD::Pg> using your operating system packages. The following command will
+test for the existence of DBD::Pg on your system:
+
+ perl -MDBD::Pg\ 999
+
+With that done, we can proceed...
+
+To avoid muddying your system, use the following script to download and
+install Netdisco and its dependencies into your home area:
+
+ curl -L http://cpanmin.us/ | perl - \
+     --notest --quiet --local-lib-contained "${HOME}/perl-profiles/netdisco" \
+     App::cpanminus \
+     App::local::lib::helper \
+     App::Netdisco
+
+Test the installation by running the following command, which should only
+produce some help text (and throw up no errors):
+
+ ~/perl-profiles/netdisco/bin/localenv netdisco-daemon --help
+
+=head1 Configuration
+
+Netdisco uses a PostgreSQL (Pg) database. You can use this application with an
+existing database, or set up a new one. At a minimum (if starting from
+scratch) you should have created a Database in Pg, and created a User in Pg
+with rights on the Database:
+
+ postgres:~$ createuser -DRSP netdisco
+ postgres:~$ createdb -O netdisco netdisco
+
+Make a directory for your local configuration, and copy the
+C<share/environments/development.yml> file from this distribution into it.
+Edit the file and change the database connection parameters for your local
+system (the C<dsn>, C<user> and C<pass>).
+
+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>).
+
+Finally, run the following script to bring you up to date:
+
+ ~/perl-profiles/netdisco/bin/localenv netdisco-db-deploy
+
+=head1 Startup
+
+Make a note of the directory containing C<development.yml> and run the
+following command to start the web server, substituting as appropriate:
+
+ DANCER_ENVIRONMENT=/change/me/dir ~/perl-profiles/netdisco/bin/localenv netdisco-web
+
+=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.
+
+For SQL debugging try the following command:
+
+ DBIC_TRACE_PROFILE=console DBIC_TRACE=1 \
+   DANCER_ENVIRONMENT=/change/me/dir \
+   ~/perl-profiles/netdisco/bin/localenv 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.
+
+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 I<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.
 
 =head1 AUTHOR
  
@@ -36,8 +134,27 @@ Oliver Gorwits <oliver@cpan.org>
  
 This software is copyright (c) 2012 by The Netdisco Developer Team.
  
-This is free software; you can redistribute it and/or modify it under
-the same terms as the Perl 5 programming language system itself.
+ 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.
 
 =cut