126 lines
4.6 KiB
Plaintext
126 lines
4.6 KiB
Plaintext
$OpenBSD: README,v 1.8 2013/03/25 07:55:10 ajacoutot Exp $
|
|
|
|
+-----------------------------------------------------------------------
|
|
| Running ${FULLPKGNAME} on OpenBSD
|
|
+-----------------------------------------------------------------------
|
|
|
|
The Puppet Dashboard has been installed into ${INSTDIR}
|
|
|
|
Configuration is done in:
|
|
${INSTDIR}/config/settings.yml
|
|
|
|
Database Configuration
|
|
======================
|
|
|
|
Before starting the Dashboard, a MySQL database must be configured in:
|
|
${INSTDIR}/config/database.yml
|
|
|
|
The following commands can be used to create the database:
|
|
# mysql -uroot -p<password>
|
|
mysql> CREATE DATABASE dashboard_production CHARACTER SET utf8;
|
|
mysql> CREATE USER 'dashboard'@'localhost' IDENTIFIED BY 'my_password';
|
|
mysql> GRANT ALL PRIVILEGES ON dashboard_production.* TO 'dashboard'@'localhost';
|
|
mysql> EXIT
|
|
|
|
The MySQL maximum packet size needs to be increased to permit larger
|
|
rows in the database; ${SYSCONFDIR}/my.cnf must be edited to include:
|
|
max_allowed_packet = 32M
|
|
Then the server must be restarted by running:
|
|
# ${RCDIR}/mysqld restart
|
|
|
|
Once the database has been setup and MySQL is up and running, the
|
|
following command must be run to create the tables:
|
|
# cd ${INSTDIR} && sudo -u _puppet-dashboard rake${MODRUBY_BINREV} RAILS_ENV=production db:migrate
|
|
|
|
Puppet Configuration
|
|
====================
|
|
|
|
By default, Puppet Dashboard will start a Rails server on port 3000.
|
|
|
|
To use the Dashboard for reports, all agent nodes must submit reports to
|
|
the master and the master must send reports to the Dashboard.
|
|
${SYSCONFDIR}/puppet/puppet.conf needs to be edited accordingly:
|
|
[agent]
|
|
report = true # this is the default
|
|
[master]
|
|
reports = store, http
|
|
reporturl = http://dashboard.domain.tld:3000/reports/upload
|
|
|
|
Node Classification
|
|
-------------------
|
|
To use the Dashboard external node classifier (ENC) alongside Puppet DSL
|
|
node definitions, the master should contain the following lines (to be
|
|
adapted accordingly):
|
|
[master]
|
|
node_terminus = exec
|
|
external_nodes = /usr/bin/env PUPPET_DASHBOARD_URL=http://localhost:3000 ${INSTDIR}/bin/external_node
|
|
|
|
Maintenance
|
|
===========
|
|
|
|
To import old Puppet reports that were created before the Dashboard got
|
|
installed, the following command can be used:
|
|
# cd ${INSTDIR} && sudo -u _puppet-dashboard rake${MODRUBY_BINREV} RAILS_ENV=production reports:import
|
|
|
|
Cron Jobs
|
|
---------
|
|
The MySQL database should be optimized on a montly basis. This can be
|
|
done by adding the following entry to the root's crontab(5):
|
|
0 0 1 * * cd ${INSTDIR} && sudo -u _puppet-dashboard rake${MODRUBY_BINREV} RAILS_ENV=production db:raw:optimize
|
|
|
|
Over time, old reports will start to accumulate which can slow down the
|
|
Dashboard. Adding the following line to the root's crontab(5) will clean
|
|
up reports older than 1 month and will run every night:
|
|
0 0 * * * cd ${INSTDIR} && sudo -u _puppet-dashboard rake${MODRUBY_BINREV} RAILS_ENV=production reports:prune upto=1 unit=mon
|
|
|
|
Upgrade
|
|
-------
|
|
After updating the Dashboard to a new release, the following command
|
|
needs to be run to update database schemas:
|
|
# cd ${INSTDIR} && sudo -u _puppet-dashboard rake${MODRUBY_BINREV} RAILS_ENV=production db:migrate
|
|
|
|
Phusion Passenger Integration (i.e. mod_rails)
|
|
==============================================
|
|
|
|
The WEBrick server script provided by Puppet Dashboard is not fit for
|
|
production. For better performance, it is advised to run the Dashboard
|
|
under Passenger along with a compatible web server.
|
|
|
|
e.g. with nginx
|
|
---------------
|
|
The nginx(8) package provides a FLAVOR for passenger support which the
|
|
version in the base system doesn't, so it must be installed first:
|
|
# pkg_add ruby-passenger nginx--passenger
|
|
|
|
Next, ${SYSCONFDIR}/nginx/nginx.conf needs to be modified with the
|
|
following requirements as a start:
|
|
|
|
* http{} block
|
|
passenger_root ${LOCALBASE}/lib/phusion-passenger;
|
|
passenger_ruby ${RUBY};
|
|
|
|
Note that the output of `passenger-config --root` will give the
|
|
"passenger_root" value.
|
|
|
|
* server{} block
|
|
listen 3000;
|
|
root ${INSTDIR}/public;
|
|
passenger_enabled on;
|
|
|
|
The nginx(8) daemon installed from packages(7) is started by the
|
|
"enginx" rc.d(8) script and obviously puppet_dashboard must be
|
|
disabled (the workers must be enabled though).
|
|
Here's a sample rc.conf.local(5) extract:
|
|
pkg_scripts="${pkg_scripts} enginx puppet_dashboard_workers"
|
|
|
|
Going further
|
|
=============
|
|
|
|
Setting up followings is out of the scope of this README but should be
|
|
considered when running Puppet Dashboard in production.
|
|
- authentication (by default, anyone can access the Dashboard)
|
|
- https (for encrypted communication)
|
|
|
|
More information is available at:
|
|
http://docs.puppetlabs.com/dashboard/manual/1.2/index.html
|