relocate repo files so ND2 is the only code

lib/App/Netdisco/Manual/Deployment.pod

@@ -0,0 +1,183 @@
+=head1 NAME
+
+App::Netdisco::Manual::Deployment - Tips and Tricks for Deployment
+
+=head1 Init and Run Control Scripts
+
+The Netdisco applications will generate RC scripts suitable for Linux systems:
+
+ bin/netdisco-web get_init_file
+ bin/netdisco-daemon get_init_file
+
+On C<systemd>-based systems please see L<our systemd
+guide|App::Netdisco::Manual::Systemd>.
+
+On BSD systems please see L<our BSD tips|App::Netdisco::Manual::BSDInstall>,
+and submit patches against the L<Daemon::Control> distribution.
+
+=head1 Enable MD5 authentication to PostgreSQL
+
+Some installations of PostgreSQL don't have MD5 authentication enabled by
+default, which blocks database connections with the default Netdisco
+configuration.
+
+If your database and Netdisco are on the same system, then the easiest
+solution is to comment out the "C<host:>" line in your C<deployment.yml> file.
+
+Alternatively, reconfigure PostgreSQL to permit MD5 auth for TCP connections
+by adding the following to your system's "C<pg_hba.conf>" file (and restarting
+the database service):
+
+ # TYPE  DATABASE  USER  ADDRESS       METHOD
+ host    all       all   127.0.0.1/32  md5
+
+=head1 Connect to PostgreSQL database on non-standard port
+
+The standard port for PostgreSQL is 5432. To connect on a different port you
+need to use the C<host> option under C<database:> config in your
+C<~/environments/deployment.yml> file. For example if connecting to a database
+on the local server:
+
+ database:
+   name: 'netdisco'
+   user: 'changeme'
+   pass: 'changeme'
+   host: 'localhost;port=5432'
+
+Obviously, substitute the C<user>, C<pass>, and actual port number for your
+local values. Note the separator character is a semicolon.
+
+=head1 Deploy without Internet access
+
+The C<netdisco-deploy> script asks for Internet access but it is possible to
+install off-line. You should download the following two files:
+
+=over 4
+
+=item *
+
+http://standards.ieee.org/develop/regauth/oui/oui.txt
+
+=item *
+
+http://downloads.sourceforge.net/project/netdisco/netdisco-mibs/latest-snapshot/netdisco-mibs-snapshot.tar.gz
+
+=back
+
+Run the C<netdisco-deploy> script but pass the OUI file name as a parameter on
+the command line:
+
+ ~/bin/netdisco-deploy ./oui.txt
+
+Then answer yes to questions, even though you're not connected to the
+Internet. For the MIBs you can simply extract the downloaded archive to the
+home directory of Netdisco.
+
+=head1 Relocating the Installation
+
+The installation process installs Netdisco self-contained to your home
+directory. The target directory can easily be changed by setting the
+C<NETDISCO_HOME> environment variable, for example:
+
+ export NETDISCO_HOME=/opt/netdisco
+
+Obviously, you'll need to substitute this wherever you see "C<~>" in the
+installation instructions. The Netdisco application will use this setting
+itself to locate files and configuration.
+
+=head1 Pass Options to the Web Frontend Daemon
+
+Simply add any options after the "C<start>" command. See other sections of
+this document for some examples.
+
+=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 start --path=/netdisco2
+
+Alternatively, can set the C<path> configuration option in your
+C<deployment.yml> file:
+
+ path: '/netdisco2'
+
+=head1 Listening Port for the Web Frontend
+
+Pass the C<--port> parameter to any of the web scripts. For example:
+
+ ~/bin/netdisco-web start --port=8080
+
+=head1 Listening Address for the Web Frontend
+
+Pass the C<--host> parameter to any of the web scripts. For example:
+
+ ~/bin/netdisco-web start --host=127.0.0.1
+
+=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<headers>, C<proxy> and C<proxy_http> modules in Apache, a
+suitable configuration would be:
+
+ ProxyPreserveHost On
+ ProxyPass / http://localhost:5000/ retry=0 timeout=60
+ ProxyPassReverse / http://localhost:5000/
+ 
+ ProxyRequests Off
+ <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, and set C<path> in your C<deployment.yml> as
+discussed above. Note there is no trailing slash in the Apache config:
+
+ ProxyPass /netdisco2 http://localhost:5000/netdisco2 retry=0 timeout=60
+ ProxyPassReverse /netdisco2 http://localhost:5000/netdisco2
+
+To delegate user authentication to Apache, use the C<trust_remote_user> or
+C<trust_x_remote_user> settings. See L<App::Netdisco::Manual::Configuration>
+for more details.
+
+=head1 SSL Support
+
+There is no SSL support in the built-in web server. This is because it's not
+straightforward to support all the SSL options, and using port 443 requires
+root privilege, which the Netdisco application should not have.
+
+You are instead recommended to run C<netdisco-web> behind a reverse proxy as
+described elsewhere in this document. Apache can easily act as an SSL reverse
+proxy.
+
+=head1 Database Backups
+
+We recommend you backup the Netdisco database regularly. You could put the
+following commands into a shell script and call it nightly from C<cron>:
+
+ DATE=`date +%Y%m%d`
+ /usr/bin/pg_dump -F c --create -f /path/to/backups/netdisco-pgsql-$DATE.dump netdisco
+ gzip -9f /path/to/backups/netdisco-pgsql-$DATE.dump
+ /usr/bin/find /path/to/backups/ -type f -ctime +30 -exec rm {} \;
+
+This will keep 30 days of backups. You don't need to stop Netdisco during the
+backup.
+
+=head1 Display all Table Rows as Default
+
+Add the following to your configuration:
+
+ table_pagesize: -1
+
+=head1 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