$OpenBSD: README,v 1.19 2016/07/02 10:50:34 sthen 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 MariaDB database must be configured in:
${INSTDIR}/config/database.yml
The following commands can be used to create the database:
# mysql -uroot -p<password>
MariaDB [(none)]> CREATE DATABASE dashboard_production CHARACTER SET utf8;
MariaDB [(none)]> CREATE USER 'dashboard'@'localhost' IDENTIFIED BY 'my_password';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON dashboard_production.* TO 'dashboard'@'localhost';
MariaDB [(none)]> EXIT
The MariaDB 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 MariaDB is up and running, the
following command must be run to create the tables:
# cd ${INSTDIR} && su -m _puppet-dashboard -c \
"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} && su -m _puppet-dashboard -c \
"rake${MODRUBY_BINREV} RAILS_ENV=production reports:import"
Note: For the above command to work, the _puppet-dashboard user must
be a member of the _puppet group.
Cron Jobs
---------
The MariaDB 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} && su -m _puppet-dashboard -c "${LOCALBASE}/bin/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} && su -m _puppet-dashboard -c "${LOCALBASE}/bin/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} && su -m _puppet-dashboard -c \
"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(8) extract:
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
