Skip to content

Latest commit

 

History

History
204 lines (132 loc) · 8.72 KB

install_from_source.markdown

File metadata and controls

204 lines (132 loc) · 8.72 KB
Raw
title layout canonical
PuppetDB 3.1 » 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.

Step 1: Install Prerequisites

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)

Step 2, Option A: Install from Source

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:

Note:

If you are using Puppet 4 or greater, the rake command below should be replaced by the rake version supplied by Puppet at /opt/puppetlabs/puppet/bin/rake

$ 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, putting a puppetdb init script in /etc/init.d on sysvinit based systems or in /etc/sysconfig on systemd based systems. This also creates a default configuration directory in /etc/puppetdb.

The puppetdb service is set to run as the puppetdb user. You will need to add this user to your system.

Create a puppetdb user and group:

$ sudo groupadd puppetdb
$ sudo useradd puppetdb -g puppetdb

Step 2, Option B: Run Directly from Source

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 test to run the test suite

Step 3, Option A: Run the SSL Configuration Script

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.

Step 3, Option B: Manually Generating and Preparing Certificates

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.

On the CA Puppet Master: Create a Certificate

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 Certificate to the PuppetDB Server

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.

Correct permissions

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.

Step 4: Configure HTTPS

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.

Step 5: Configure Database

If this is a production deployment, you should confirm and configure your database settings:

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.

Set puppetdb ownership on puppetdb system files:

$ sudo chown -R puppetdb:puppetdb /etc/puppetdb
$ sudo chown -R puppetdb:puppetdb /var/lib/puppetdb

Step 6: Start the PuppetDB Service

If you installed PuppetDB from source, you can start PuppetDB by running the following:

$ sudo service 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.

Finish: Connect Puppet to PuppetDB

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.