Developer Deployment

Getting the Source

You can browse the source code at

For anonymous access to the Candlepin source code, feel free to clone the repository:

$ git clone git://

Candlepin committers can clone the repository using the ssh url, which is required if you want to push changes into the repo (and of course you need permission to do so).

$ git clone

For more information on working with Git, checkout the Spacewalk GitGuide.

Install Dependencies

Instructions for Fedora 22.

Candlepin uses buildr as its build tool (primarily because we don’t like maven).

  • Install dependencies.

    $ sudo dnf install ruby rubygems ruby-devel gcc make gettext tomcat java-1.8.0-openjdk-devel liquibase postgresql-jdbc openssl libxml2-python qpid-proton-c-devel qpid-proton-c jss

    NOTE: You may want to install Java 1.6.0 or 1.7.0 depending on OS version.

  • Update rubygems.

    $ sudo gem update --system
  • Become root.

    $ sudo -s

    # export JAVA_HOME=/usr/lib/jvm/java-1.8.0/

    NOTE: This should match the Java version specified above.

  • Install bundler.

    # gem install bundler
  • Return to your normal user account and candlepin.git checkout.
  • Install the Ruby dependencies.

    $ bundle install

Make sure your tomcat directory within /var/cache has group permissions (chmod 775 /var/cache/tomcat)


If you have multiple JVMs on your system and are getting RuntimeError : can't create Java VM, you may need to set your JVM via alternatives --config java and alternatives --config javac. Additionally, you may need to use this JAVA_HOME path: /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.**.x86_64/, where the ** should be filled in with the appropriate build version (matching the proper directory from ls /usr/lib/jvm/).

The following will compile and package candlepin into a war and api jar in target/. Testing will be covered below hence the test=no param.

$ cd candlepin/
$ buildr clean test=no package

Configure A Database

Candlepin is typically deployed against PostgreSQL, but schema is provided for Oracle and MySQL as well.


  1. Install PostgresSQL.

    $ sudo dnf install -y postgresql-server postgresql
  2. Initialize PostgreSQL.

    $ sudo postgresql-setup initdb
  3. Update /var/lib/pgsql/data/pg_hba.conf to be trust instead of ident:

    local   all         all                               trust
    host    all         all          trust
    host    all         all         ::1/128               trust
  4. Enable and start the PostgreSQL server.

    $ sudo systemctl enable postgresql
    $ sudo systemctl start postgresql
  5. Create the candlepin user:

    $ sudo su - postgres -c 'createuser -dls candlepin'

Deploy Candlepin

The preferred method for deploying Candlepin from source is using the supplied deploy script in the server/bin directory. This script will generate the database schema, populate your PostgreSQL database, create the certs for Tomcat, deploy the war file, and restart tomcat. It can also be used to deploy to a Oracle/MySQL databases, and pre-load our test data.

Remember to set JAVA_HOME for buildr to work.

$ server/bin/deploy

Test that the application is listening with:

$ curl -k -u admin:admin "https://localhost:8443/candlepin/status"

Deploy Script Options

The deploy script can be customized with a number of environment variables, or you can set these permanently in ~/.candlepinrc.

Environment Variables

if set, this enables schema generation and population. Can also be achieved with the -g argument to deploy script.
if set, will always regenerate new ssl certificates (both for the ca used in creating client certificates, and for the server cert). Can also be achieved with the -f argument to the deploy script.
use this to force the CN in your certificate. ie, set it to localhost if you’re only running a client from your machine.
set to 1 to automatically load our test data as defined in server/bin/test_data.json. This is a selection of product, subscription, and org info that nicely covers all the functionality of Candlepin. Subscriptions point to fake content however and thus cannot be used with an actual client. Can also be specified with the -t argument to the deploy script.
if set, will use the jdbc logdriver for logging SQL calls. This can also be specified with the -l argument to the deploy script.
if set, will use AutoConf to automatically generate candlepin.conf. Can also be specified with the -a argument to the deploy script.
if set, will use notify-send to notify you when deployment has finished
set to the location of your tomcat installation, /opt/apache-tomcat-6.0.20 or /var/lib/tomcat (default).
if set, includes the resources for testing candlepin in hosted mode. Can also be specified with the -H argument to the deploy script. If used with AUTOCONF, the default adapters will be overriden by hostedtest adapters in candlepin.conf

Script Arguments

The deploy script may also be customized/configured by providing command-line arguments during invocation. Some of these overlap with those triggered by environment variables, providing shorter alternatives to triggering the options above.

Alternate to the FORCECERT variable. If set, the deploy script will generate new SSL certificates.
Alternate to the GENDB variable. If set, the current database, if any, will be dropped and a new schema will be generated.
Alternate to the TESTDATA variable. If set, the database will be populated with the test data defined in server/bin/test_data.json after a successful deployment.
-l <log_driver>
Alternate to the LOGDRIVER variable. If set, Candlepin will use the specified log driver for logging SQL calls.
-o, -m
Specifies alternate database backends to use instead of PostgreSQL; -o for Oracle and -m for MySQL. Only one alternate should be specified for a given invocation.
Alternate to the AUTOCONF variable. If set, AutoConf will be used to automatically generate a new candlepin.conf file.
Enabled verbose/noisy output. Useful, primarily, for debugging issues that may arise during deployment.
Alternate to the HOSTEDTEST variable. If set, resources to test candlepin in hosted mode will be included in the candlepin war. If used with -a, the default adapters will be overriden by hostedtest adapters in candlepin.conf
Alternate to the TESTREPO variable. If set, testing repositories will be created.

Manual Deployment

If for some reason you wish to deploy manually, you can generate the candlepin war file and deploy it into tomcat easily.

$ buildr clean test=no package

This should result in candlepin-XYZ.war file being created in the target/ directory. Deploy the resulting war file to your favorite servlet container.


There are a few things that some folks have hit while deploying Candlepin.

Database Initialization

IMPORTANT: No matter which database you are using, you will most likely need to initialize it once and only once after it is created. This process creates some core entries in the database required for Candlepin to operate properly. If you are using our deploy script, this will be handled for you automatically. Otherwise you can trigger this by hitting the following URL:

$ wget -qO- http://localhost:8080/candlepin/admin/init

Repeated calls to this URL are not required, but will be harmless.

Tomcat not listening on the right ports

If you see something amiss, an easy first thing to check is to ensure that tomcat is running and listening on the right ports.

# netstat -anlp | grep java
tcp        0      0 :::8080                     :::*                        LISTEN      21864/java
tcp        0      0 :::8443                     :::*                        LISTEN      21864/java
tcp        0      0 ::ffff:       :::*                        LISTEN      21864/java
tcp        0      0 :::8009                     :::*                        LISTEN      21864/java
unix  2      [ ]         STREAM     CONNECTED     793153 21864/java

The important things here are 8080 (the default HTTP listener), and 8443 (the SSL listener). If you don’t have both of those, try setting FORCECERT=1 and trying again. Consulting catalina.out is always useful as well.

HornetQ Upgrade Errors

The hornetq journal doesn’t seem to like being used by new versions. If you see an exception on startup like:

SEVERE: Failure in initialisation
java.lang.IllegalStateException: Invalid record type 23
at org.hornetq.core.persistence.impl.journal.JournalStorageManager.loadBindingJournal(

You need to clear your journal:

$ rm -rf /var/lib/candlepin/hornetq*
Last modified on 21 May 2019