184 lines
5.7 KiB
Plaintext
184 lines
5.7 KiB
Plaintext
=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
|