Installing from packages

On this page:

If you are running Puppet Enterprise, you do not need to install PuppetDB, as PuppetDB is already installed as part of PE.

This page describes how to manually install and configure PuppetDB from the official packages.

Additionally, these instructions may be useful for understanding PuppetDB's various moving parts, and can be helpful if you need to create your own PuppetDB module.

After following these instructions, you must connect your Puppet Server(s) to PuppetDB. (If you use a standalone Puppet deployment, you will need to connect every node to PuppetDB.)
If this is a production deployment, review the scaling recommendations before installing. You should ensure that your PuppetDB server will be able to comfortably handle your site's load.

Step 1: Install and configure Puppet

If Puppet isn't fully installed and configured on your PuppetDB server:

1. Install Puppet Core.

2. Request, sign, and retrieve a certificate for the node.

Your PuppetDB server should be running Puppet agent and have a signed certificate from your Puppet Server. If you run puppet agent --test, it should successfully complete a run, ending with Notice: Applied catalog in X.XX seconds.

If Puppet doesn't have a valid certificate when PuppetDB is installed, run the SSL config script and edit the config file or manually configure PuppetDB's SSL credentials so that the Puppet Server can connect to PuppetDB.

Step 2: Enable the Puppet Platform package repository

If you didn't already use it to install Puppet, you need to enable the Puppet Platform package repository.

Step 3: Install PuppetDB

Use Puppet to install PuppetDB:

Copy

$ sudo puppet resource package puppetdb ensure=latest

Step 4: Configure database

Set up a PostgreSQL server and configure PuppetDB to use it. If your PostgreSQL node is on a separate server than PuppetDB, configure an SSL connection, otherwise your database communication will be in plaintext over the network.

If the cleartext listener is disabled, before starting the PuppetDB service:

Ensure ssl-* settings are enabled.
Ensure that the following files exist:
- /etc/puppetlabs/puppetdb/ssl/ca.pem
- /etc/puppetlabs/puppetdb/ssl/private.pem
You can create these files using the puppetdb ssl-setup command.

Step 5: Start the PuppetDB service

Use Puppet to start the PuppetDB service and enable it on startup.

Copy

$ sudo puppet resource service puppetdb ensure=running enable=true

You must also configure your PuppetDB server's firewall to accept incoming connections on port 8081.

PuppetDB is now fully functional and ready to receive facts, catalogs, and reports from any number of Puppet Servers.

Finish: Connect Puppet to PuppetDB

You should now configure your Puppet Server(s) to connect to PuppetDB.

If you use a standalone Puppet site, you should configure every node to connect to PuppetDB.

Troubleshooting installation problems

Check the log file (/var/log/puppetlabs.puppetdb/puppetdb.log), and see whether PuppetDB knows what the problem is.
If PuppetDB is running but the Puppet Server can't reach it, check PuppetDB's [jetty] configuration to see which port(s) it is listening on, then attempt to reach it by Telnet (telnet <HOST> <PORT>) from the Puppet Server. If you can't connect, the firewall may be blocking connections. If you can, Puppet may be attempting to use the wrong port, or PuppetDB's keystore may be misconfigured (see below).
Check whether any other service is using PuppetDB's port and interfering with traffic.
Check PuppetDB's [jetty] configuration and the /etc/puppetlabs/puppetdb/ssl directory, and make sure it has the necesary SSL files created. If it didn't create these during installation, you will need to run the SSL config script and edit the config file before a Puppet Server can contact PuppetDB.