diff --git a/Netdisco/Changes b/Netdisco/Changes index f922105b..6a522915 100644 --- a/Netdisco/Changes +++ b/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] diff --git a/Netdisco/bin/netdisco-daemon b/Netdisco/bin/netdisco-daemon index c8426cff..ed4e1b2b 100755 --- a/Netdisco/bin/netdisco-daemon +++ b/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 + +=back + +=cut diff --git a/Netdisco/bin/netdisco-daemon-fg b/Netdisco/bin/netdisco-daemon-fg index e00b5fb8..718b6e88 100755 --- a/Netdisco/bin/netdisco-daemon-fg +++ b/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 + +=back + +=cut diff --git a/Netdisco/bin/netdisco-db-deploy b/Netdisco/bin/netdisco-db-deploy index ae0cea79..fcf39172 100755 --- a/Netdisco/bin/netdisco-db-deploy +++ b/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). +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 diff --git a/Netdisco/bin/netdisco-deploy b/Netdisco/bin/netdisco-deploy index 04f3b256..d2b040c9 100755 --- a/Netdisco/bin/netdisco-deploy +++ b/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). +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.'; diff --git a/Netdisco/bin/netdisco-web b/Netdisco/bin/netdisco-web index 938f2d18..ef1b9107 100755 --- a/Netdisco/bin/netdisco-web +++ b/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 + +=back + +=cut diff --git a/Netdisco/bin/netdisco-web-fg b/Netdisco/bin/netdisco-web-fg index a66965e6..a8de4fa0 100755 --- a/Netdisco/bin/netdisco-web-fg +++ b/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 + +=back + +=cut diff --git a/Netdisco/lib/App/Netdisco.pm b/Netdisco/lib/App/Netdisco.pm index b6a8b05c..33668af5 100644 --- a/Netdisco/lib/App/Netdisco.pm +++ b/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, C and C). -Optionally, in the same file uncomment and edit the C setting -to be appropriate for your local site. +In the same file uncomment and edit the C setting to be +appropriate for your local site. Optionally, set the C 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 page. See also the L documentation. - =head2 User Rights With the default configuration user authentication is disabled and the default diff --git a/Netdisco/lib/App/Netdisco/Manual/Deployment.pod b/Netdisco/lib/App/Netdisco/Manual/Deployment.pod new file mode 100644 index 00000000..eed82863 --- /dev/null +++ b/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). + +After enabling the C and C modules in Apache, a suitable +configuration would be: + + ProxyPass / http://localhost:5000/ + ProxyPassReverse / http://localhost:5000/ + + + Order allow,deny + Allow from all + + +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 page. See also the L and L +documentation. + +=cut diff --git a/Netdisco/lib/App/Netdisco/Developing.pod b/Netdisco/lib/App/Netdisco/Manual/Developing.pod similarity index 86% rename from Netdisco/lib/App/Netdisco/Developing.pod rename to Netdisco/lib/App/Netdisco/Manual/Developing.pod index 9bf20491..c71711b5 100644 --- a/Netdisco/lib/App/Netdisco/Developing.pod +++ b/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" these environment variables are used to load two YAML files: C and C<< .yml >> where -C<< >> is typically either C or C. +C<< >> is typically either C or C. The concept of "environments" allows us to have some shared "master" config between all instances of the application (C), and then settings for specific circumstances. Typically this might be logging levels, for -example. The default file which C loads is C +example. The default file which C loads is C but you can override it by setting the "C" environment variable. +The file is located in an C 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" environment variable. The location of +the folder alone can be overridden using the "C" environment +variable. + Dancer loads the config using YAML, merging data from the two files. Config is made available via Dancer's C subroutine, which is exported. So now the C 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 and L 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 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 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 -instructions). The C script uses L to daemonize -this simple web server so you can fire-and-forget the Netdisco web app without -much trouble at all. This script in turn calls C which is the -real Dancer application, that runs in the foreground if called on its own. +user, and actually ships with a fast, preforking web server engine. The +C script uses L to daemonize this simple web +server so you can fire-and-forget the Netdisco web app without much trouble at +all. This script in turn calls C which is the real Dancer +application, that runs in the foreground if called on its own. All web app code lives below L, but there are also some helper routines in L (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 and C folder trees for changes, and you +probably want to switch to the C 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. It's likely this name will change in the future. +=head1 Other Noteable Technology + +=head2 C + +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 +module is responsible for re-setting Perl's environment to point at the new +library. + +=head2 C + +This is simply a sane replacement for the CPAN shell. Don't ever bother with +the CPAN shell again, just use the L client which comes with this +distribution. We install Netdisco using C. + +=head2 C + +This is a companion to C which provides the C script you +see referenced in the documentation. It's run automatically by Netdisco to +locate its C 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 environment variable. + +=head2 C + +A replacement for C which provides proper C semantics. You +have to take a bit of care unfortunately over things like C statements +though. However it's a lot cleaner than C in many cases. See the +L for further details. + +=head2 C + +Anyone familiar with the concept of an I 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 - - - - - - - - - - - - - - - - - - - - - - - diff --git a/Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod b/Netdisco/lib/App/Netdisco/Manual/ReleaseNotes.pod new file mode 100644 index 00000000..548e5183 --- /dev/null +++ b/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 recommended to read this document each time you +install and upgrade. + +=head1 2.005000_003 + +=head2 Incompatible Changes + +The default environment configuration file C has been renamed +to C. This better reflects that users are not developers, and +also fits with the default for PSGI compatible cloud deployment services. + +Please B 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 environment variable. This defaults to your own +home directory. + +=cut diff --git a/TODO b/TODO index 464b0da0..9c2c9701 100644 --- a/TODO +++ b/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