moar documentation

Netdisco/Changes

@@ -1,4 +1,4 @@
-2.005000_003 - 
+2.005000_003 - 2013-03-05
 
   [NEW FEATURES]
 
@@ -14,6 +14,7 @@
   * Add log messages to the Daemon
   * Use Path::Class for path and file name construction consistently
   * All links and redirects are now relative
+  * More documentation on developing and deployment
 
   [BUG FIXES]
 

Netdisco/bin/netdisco-daemon

@@ -38,3 +38,19 @@ Daemon::Control->new({
   stderr_file => file($log_dir, 'netdisco-daemon.log'),
   stdout_file => file($log_dir, 'netdisco-daemon.log'),
 })->run;
+
+=head1 NAME
+
+netdisco-daemon - Job Control Daemon for Netdisco
+
+=head1 SEE ALSO
+
+=over 4
+
+=item *
+
+L<App::Netdisco>
+
+=back
+
+=cut

Netdisco/bin/netdisco-daemon-fg

@@ -93,3 +93,19 @@ sub restart_worker {
   debug "restarting worker $e->{wid}";
   $self->restart_worker($e->{wid});
 }
+
+=head1 NAME
+
+netdisco-daemon-fg - Job Control for Netdisco
+
+=head1 SEE ALSO
+
+=over 4
+
+=item *
+
+L<App::Netdisco>
+
+=back
+
+=cut

Netdisco/bin/netdisco-db-deploy

@@ -16,7 +16,7 @@ This script upgrades or initialises a Netdisco database schema.
 Pre-existing requirements are that there be a database table created and a
 user with rights to create tables in that database. Both the table and user
 name must match those configured in your environment YAML file (default
-C<environments/development.yml>).
+C<~/environments/deployment.yml>).
 
 Simply run this script, which connects to the database and runs without user
 interaction. If there's no Nedisco schema, it is deployed. If there's an
@@ -37,7 +37,7 @@ Version 2 is the "classic" Netdisco database schema as of Netdisco 1.1
 
 =item *
 
-Version 3 (and onwards) adds patches for Netdisco 1.2
+Version 5 (and onwards) adds patches for Netdisco 1.2
 
 =back
 

Netdisco/bin/netdisco-deploy

@@ -53,7 +53,7 @@ these is an optional service which the user is asked to confirm.
 Pre-existing requirements are that there be a database table created and a
 user with rights to create tables in that database. Both the table and user
 name must match those configured in your environment YAML file (default
-C<environments/development.yml>).
+C<~/environments/deployment.yml>).
 
 This script will download the latest MAC address vendor prefix data from the
 Internet, and update the OUI table in the database. Hence Internet access is
@@ -71,7 +71,7 @@ say 'Before we continue, the following prerequisites must be in place:';
 say ' * Internet access';
 say ' * Database added to PostgreSQL for Netdisco';
 say ' * User added to PostgreSQL with rights to the Netdisco Database';
-say ' * "environments/development.yml" file configured with Database dsn/user/pass';
+say ' * "~/environments/deployment.yml" file configured with Database dsn/user/pass';
 say ' * A full backup of any existing Netdisco database data';
 say '';
 say 'You will be asked to confirm all changes to your system.';

Netdisco/bin/netdisco-web

@@ -38,3 +38,19 @@ Daemon::Control->new({
   stderr_file => file($log_dir, 'netdisco-web.log'),
   stdout_file => file($log_dir, 'netdisco-web.log'),
 })->run;
+
+=head1 NAME
+
+netdisco-web - Web Application Server for Netdisco
+
+=head1 SEE ALSO
+
+=over 4
+
+=item *
+
+L<App::Netdisco>
+
+=back
+
+=cut

Netdisco/bin/netdisco-web-fg

@@ -35,3 +35,19 @@ set plack_middlewares => [
 
 use App::Netdisco::Web;
 dance;
+
+=head1 NAME
+
+netdisco-web-fg - Web Application for Netdisco
+
+=head1 SEE ALSO
+
+=over 4
+
+=item *
+
+L<App::Netdisco>
+
+=back
+
+=cut

Netdisco/lib/App/Netdisco.pm

@@ -125,8 +125,9 @@ template from this distribution:
 Edit the file and change the database connection parameters to match those for
 your local system (that is, the C<dsn>, C<user> and C<pass>).
 
-Optionally, in the same file uncomment and edit the C<domain_suffix> setting
+In the same file uncomment and edit the C<domain_suffix> setting to be
-to be appropriate for your local site.
+appropriate for your local site. Optionally, set the C<no_auth> value to true
+if you wish to skip user authentication in the web interface.
 
 =head1 Bootstrap
 
@@ -167,18 +168,6 @@ 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.
 
-=head2 SQL and HTTP Trace
-
-For SQL debugging try the following commands:
-
- DBIC_TRACE_PROFILE=console DBIC_TRACE=1 ~/bin/localenv ~/bin/netdisco-web-fg
- DBIC_TRACE_PROFILE=console DBIC_TRACE=1 ~/bin/localenv ~/bin/netdisco-daemon-fg
-
-=head2 Deployment
-
-Other ways to run and host the web application can be found in the
-L<Dancer::Deployment> page. See also the L<plackup> documentation.
-
 =head2 User Rights
 
 With the default configuration user authentication is disabled and the default

Netdisco/lib/App/Netdisco/Manual/Deployment.pod

@@ -0,0 +1,49 @@
+=head1 NAME
+
+App::Netdisco::Manual::Deployment - Tips and Tricks for Deployment
+
+=head1 Non-root Hosting
+
+Netdisco will assume its web site is hosted at the apex of your server - that
+is, the document root. To relocate the web application, pass the C<--path>
+parameter to the web startup script:
+
+ ~/bin/netdisco-web --path /netdisco2
+
+=head1 Behind a Proxy
+
+By default the web application daemon starts listening on port 5000 and goes 
+into the background. This is ideal for hosting behind a web proxy (e.g. Apache
+with C<mod_proxy>).
+
+After enabling the C<proxy> and C<proxy_http> modules in Apache, a suitable
+configuration would be:
+
+ ProxyPass / http://localhost:5000/
+ ProxyPassReverse / http://localhost:5000/
+ 
+ <Proxy *>
+   Order allow,deny
+   Allow from all
+ </Proxy>
+
+To combine this with Non-root Hosting as above, simply change the paths
+referenced in the configuration like so (and use C<--path> option):
+
+ ProxyPass /netdisco2 http://localhost:5000/
+ ProxyPassReverse /netdisco2 http://localhost:5000/
+
+=head2 SQL and HTTP Trace
+
+For SQL debugging try the following commands:
+
+ DBIC_TRACE_PROFILE=console DBIC_TRACE=1 ~/bin/localenv ~/bin/netdisco-web-fg
+ DBIC_TRACE_PROFILE=console DBIC_TRACE=1 ~/bin/localenv ~/bin/netdisco-daemon-fg
+
+=head2 Further Reading...
+
+Other ways to run and host the web application can be found in the
+L<Dancer::Deployment> page. See also the L<plackup> and L<starman>
+documentation.
+
+=cut

Netdisco/lib/App/Netdisco/Manual/Developing.pod

@@ -1,3 +1,7 @@
+=head1 NAME
+
+App::Netdisco::Manual::Developing - Notes for contributors
+
 =head1 DEVELOPER NOTES
 
 This document aims to help developers understand the intent and design of the
@@ -64,15 +68,21 @@ several environment variables in order to locate the configuration files.
 
 Then, when we call "C<use Dancer>" these environment variables are used to
 load two YAML files: C<config.yml> and C<< <environment>.yml >> where
-C<< <environment> >> is typically either C<production> or C<development>.
+C<< <environment> >> is typically either C<deployment> or C<development>.
 
 The concept of "environments" allows us to have some shared "master" config
 between all instances of the application (C<config.yml>), and then settings
 for specific circumstances. Typically this might be logging levels, for
-example. The default file which C<App::Netdisco> loads is C<development.yml>
+example. The default file which C<App::Netdisco> loads is C<deployment.yml>
 but you can override it by setting the "C<DANCER_ENVIRONMENT>" environment
 variable.
 
+The file is located in an C<environments> folder which defaults to being in
+the user's home directory. The name (or full path) of the folder can be
+overriden using the "C<DANCER_ENVDIR>" environment variable. The location of
+the folder alone can be overridden using the "C<NETDISCO_HOME>" environment
+variable.
+
 Dancer loads the config using YAML, merging data from the two files. Config is
 made available via Dancer's C<setting('foo')> subroutine, which is exported.
 So now the C<foo> setting in either config file is easily accessed.
@@ -208,6 +218,10 @@ routines are more manageable, and easier to maintain. You'll also notice use
 of modules such as L<Net::MAC> and L<NetAddr::IP::Lite> to simplify and make
 more robust the handling of data.
 
+In fact, many sections of the web application have been factored out into
+separate Plugin modules. For more information see the
+L<App::Netdisco::Web::Plugin> manual page.
+
 =head2 Running the Web App
 
 Dancer apps conform to the "PSGI" standard interface for web applications,
@@ -215,16 +229,24 @@ which makes for easy deployment under many stacks such as Apache, FCGI, etc.
 See L<Dancer::Deployment> for more detail.
 
 At a minimum Netdisco can run from within its own user area as an unprivileged
-user, and ships with a simple web server engine (see the user docs for
+user, and actually ships with a fast, preforking web server engine. The
-instructions). The C<netdisco-web> script uses L<Daemon::Control> to daemonize
+C<netdisco-web> script uses L<Daemon::Control> to daemonize this simple web
-this simple web server so you can fire-and-forget the Netdisco web app without
+server so you can fire-and-forget the Netdisco web app without much trouble at
-much trouble at all. This script in turn calls C<netdisco-web-fg> which is the
+all. This script in turn calls C<netdisco-web-fg> which is the real Dancer
-real Dancer application, that runs in the foreground if called on its own.
+application, that runs in the foreground if called on its own.
 
 All web app code lives below L<App::Netdisco::Web>, but there are also some
 helper routines in L<App::Netdisco::Util::Web> (for example sorting device
 port names).
 
+If you're working on code in the web application, it's possible to have the
+app restart itself each time you save a file in your editor. The following
+command will watch the C<lib> and C<share> folder trees for changes, and you
+probably want to switch to the C<development.yml> dancer configuration for
+additional logging:
+
+ DANCER_ENVIRONMENT=development ~/bin/localenv plackup -R lib,share bin/netdisco-web-fg
+
 =head2 Authentication
 
 Dancer includes (of course) good session management using cookies and a memory
@@ -425,27 +447,43 @@ There is currently only one table, the port control job queue, in
 L<App::Netdisco::Daemon::DB::Result::Admin>. It's likely this name will change
 in the future.
 
+=head1 Other Noteable Technology
+
+=head2 C<local::lib>
+
+This is the system used to install Netdisco and all its Perl dependencies into
+a folder independent of the system's Perl libraries. It means Netdisco can be
+self-contaned and at the same time relocated anywhere. The L<local::lib>
+module is responsible for re-setting Perl's environment to point at the new
+library.
+
+=head2 C<App::cpanminus>
+
+This is simply a sane replacement for the CPAN shell. Don't ever bother with
+the CPAN shell again, just use the L<cpanm> client which comes with this
+distribution. We install Netdisco using C<cpanm>.
+
+=head2 C<App::local::lib::helper>
+
+This is a companion to C<local::lib> which provides the C<localenv> script you
+see referenced in the documentation. It's run automatically by Netdisco to
+locate its C<local::lib> folder (that is, works around the bootstrapping
+problem where the shipped app doesn't know to where it is relocated). We can
+help things along by setting the C<NETDISCO_HOME> environment variable.
+
+=head2 C<Try::Tiny>
+
+A replacement for C<eval> which provides proper C<try/catch> semantics. You
+have to take a bit of care unfortunately over things like C<return> statements
+though. However it's a lot cleaner than C<eval> in many cases. See the
+L<documentation|Try::Tiny> for further details.
+
+=head2 C<Role::Tiny>
+
+Anyone familiar with the concept of an I<interface> from other programming
+languages might understand what a role is. It's class functionality, often
+also called a "trait", which is composed into a class at run-time. This module
+allows the Daemon workers to dynamically assume different roles according to
+configuration.
+
 =cut
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod

@@ -0,0 +1,29 @@
+=head1 NAME
+
+App::Netdisco::Manual::ReleaseNotes - Release Notes
+
+=head1 Introduction
+
+This document will list only the most important changes with each release of
+Netdisco. You are B<STRONGLY> recommended to read this document each time you
+install and upgrade.
+
+=head1 2.005000_003
+
+=head2 Incompatible Changes
+
+The default environment configuration file C<develpment.yml> has been renamed
+to C<deployment.yml>. This better reflects that users are not developers, and
+also fits with the default for PSGI compatible cloud deployment services.
+
+Please B<rename or copy> your environment file:
+
+ mv ~/environments/development.yml ~/environments/deployment.yml
+
+=head2 Other Changes
+
+The installation is now relocateable outside of a user's home directory by
+setting the C<NETDISCO_HOME> environment variable. This defaults to your own
+home directory.
+
+=cut

TODO

@@ -22,17 +22,5 @@ DAEMON
 CORE
 ====
 
-* ditch ~/bin ?
 * pseudo-device support
 * VRF support
-* docs notes
-  - start release notes page
-  - plackup -R option
-  - localenv
-  - Try::Tiny
-  - Role::Tiny
-  - before and before_template hooks
-  - running from git clone of netdisco-ng
-  - plackup --path for relocating
-  - NETDISCO_HOME
-  - development -> deployment