$OpenBSD: README,v 1.3 2013/03/12 10:59:50 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
Note that this command *must* also be run after a Puppet Dashboard
upgrade.
Running the Dashboard
=====================
These commands will start a Rails server on port 3000 then start the
delayed job workers to asynchronously process resource-intensive tasks.
They can be added to rc.conf.local(5) to start Puppet Dashboard at boot
time.
# cd ${INSTDIR} && sudo -u _puppet-dashboard ./script/server -d -e production 2>/dev/null
# cd ${INSTDIR} && sudo -u _puppet-dashboard env RAILS_ENV=production script/delayed_job -p dashboard -n 4 -m start 2>/dev/null
Puppet Configuration
====================
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
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)
- Passenger (with Apache or Nginx for better performance)
More information is available at:
http://docs.puppetlabs.com/dashboard/manual/1.2/index.html
