| title | layout | canonical |
|---|---|---|
PuppetDB 2.2 » Installing PuppetDB from Source |
default |
/puppetdb/latest/install_from_source.html |
Note: If you are running Puppet Enterprise 3.0 or later, PuppetDB is already installed as part of PE. You do not need to install it separately.
This page describes how to install PuppetDB from an archive of the source code, or alternately how to run it directly from source without installing.
If possible, we recommend installing PuppetDB with the puppetlabs-puppetdb module or from packages; either approach will be easier. However, if you are testing a new version, developing PuppetDB, or installing it on a system not supported with official packages, you will need to install it from source.
Note:
If you'd like to migrate existing exported resources from your ActiveRecord storeconfigs database, please see the documentation on Migrating Data.
Use your system's package tools to ensure that the following prerequisites are installed:
- Facter, version 1.7.0 or higher
- JDK 1.7 or higher
- Leiningen
- Git (for checking out the source code)
Install Leiningen:
$ mkdir ~/bin && cd ~/bin
$ curl -L 'https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein' -o lein --tlsv1
$ chmod ugo+x lein
$ ./lein
# symlink lein to somewhere in your $PATH
$ sudo ln -s /full/path/to/bin/lein /usr/local/bin
Run the following commands:
$ mkdir -p ~/git && cd ~/git
$ git clone git://github.com/puppetlabs/puppetdb
$ cd puppetdb
$ rake package:bootstrap
$ sudo LEIN_ROOT=true rake install
This will install PuppetDB, put a puppetdb init script in /etc/init.d and create a default configuration directory in /etc/puppetdb.
While installing from source is useful for simply running a development version for testing, for development it's better to be able to run directly from source, without any installation step.
Run the following commands:
$ mkdir -p ~/git && cd ~/git
$ git clone git://github.com/puppetlabs/puppetdb
$ cd puppetdb
# Download the dependencies
$ lein deps
This will let you develop on PuppetDB and see your changes by simply editing the code and restarting the server. It will not create an init script or default configuration directory. To start the PuppetDB service when running from source, you will need to run the following:
$ lein run services -c /path/to/config.ini
A sample config file is provided in the root of the source repo: config.sample.ini. You can also provide a conf.d-style directory instead of a flat config file.
Other useful commands for developers:
lein testto run the test suite
If your PuppetDB server has puppet agent installed, has received a valid certificate from your site's Puppet CA, and you installed PuppetDB from source, then PuppetDB can re-use Puppet's certificate.
Run the following command:
$ sudo /usr/sbin/puppetdb ssl-setup
This will copy the relevant PEM files from your Puppet installation into /etc/puppetdb/ssl and can be used to correct your SSL configuration in jetty.ini to use those files.
You should now configure HTTPS in PuppetDB's config file(s); see below.
If you will not be using Puppet on your PuppetDB server, you must manually create a certificate, and copy the relevant files into place. This is more of an involved process, so we highly recommend installing Puppet and using Option A above, even if you will not be using puppet agent to manage the PuppetDB server.
Use puppet cert generate to create a certificate and private key for your PuppetDB server. Run the following, using your PuppetDB server's hostname:
$ sudo puppet cert generate puppetdb.example.com
Copy the CA certificate, the PuppetDB certificate, and the PuppetDB private key to your PuppetDB server. Run the following on your CA puppet master server, using your PuppetDB server's hostname:
$ sudo scp $(puppet master --configprint ssldir)/ca/ca_crt.pem puppetdb.example.com:/etc/puppetdb/ssl/ca.pem
$ sudo scp $(puppet master --configprint ssldir)/private_keys/puppetdb.example.com.pem puppetdb.example.com:/etc/puppetdb/ssl/private.pem
$ sudo scp $(puppet master --configprint ssldir)/certs/puppetdb.example.com.pem puppetdb.example.com:/etc/puppetdb/ssl/public.pem
You may now log out of your puppet master server.
On your PuppetDB, ensure the certificates have the correct permissions:
$ sudo chown puppetdb:puppetdb /etc/puppetdb/ssl/*.pem
$ sudo chmod 0600 /etc/puppetdb/ssl/*.pem
You should now configure HTTPS in PuppetDB's config file(s); see below.
In your PuppetDB configuration file(s), edit the [jetty] section. If you installed from source, edit /etc/puppetdb/conf.d/jetty.ini; if you are running from source, edit the config file you chose.
The [jetty] section should contain the following, with your PuppetDB server's hostname and desired ports:
[jetty]
# Optional settings:
host = puppetdb.example.com
port = 8080
# Required settings:
ssl-host = puppetdb.example.com
ssl-port = 8081
ssl-cert = /etc/puppetdb/ssl/public.pem
ssl-key = /etc/puppetdb/ssl/private.pem
ssl-ca-cert = /etc/puppetdb/ssl/ca.pem
If you don't want to do unsecured HTTP at all, you can omit the host and port settings. However, this may limit your ability to use PuppetDB for other purposes, including viewing its performance dashboard. A reasonable compromise is to set host to localhost, so that unsecured traffic is only allowed from the local box; tunnels can then be used to gain access to the performance dashboard.
If this is a production deployment, you should confirm and configure your database settings:
- Deployments of 100 nodes or fewer can continue to use the default built-in database backend, but should increase PuppetDB's maximum heap size to at least 1 GB.
- Large deployments should set up a PostgreSQL server and configure PuppetDB to use it. You may also need to adjust the maximum heap size.
You can change PuppetDB's database at any time, but note that changing the database does not migrate PuppetDB's data, so the new database will be empty. However, as this data is automatically generated many times a day, PuppetDB should recover in a relatively short period of time.
If you installed PuppetDB from source, you can start PuppetDB by running the following:
$ sudo /etc/init.d/puppetdb start
And if Puppet is installed, you can permanently enable PuppetDB by running:
$ sudo puppet resource service puppetdb ensure=running enable=true
If you are running PuppetDB from source, you should start it as follows:
# From the directory in which PuppetDB's source is stored:
$ lein run services -c /path/to/config.ini
PuppetDB is now fully functional and ready to receive catalogs and facts from any number of puppet master servers.
You should now configure your puppet master(s) to connect to PuppetDB.
If you use a standalone Puppet site, you should configure every node to connect to PuppetDB.