=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