Skip to content

[M] CANDLEPIN-1101: Refreshed Candlepin developer documentation #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nikosmoum merged 1 commit into from
Jan 15, 2026
Merged

[M] CANDLEPIN-1101: Refreshed Candlepin developer documentation #297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions docs/candlepin/building_rpms_with_tito.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,6 @@ The latest git commit is *f05b8a5* which is *11* commits since the last tag:
*candlepin-0.0.40-1*.

## Other tito resources
* [tito github repo](http://github.com/dgoodwin/tito)
* [Tito introduction into Spacewalk](https://fedorahosted.org/spacewalk/wiki/Tito)
* [Spacewalk release cycle using Tito](https://fedorahosted.org/spacewalk/wiki/ReleaseProcess)
* [Building test rpms using Tito](https://fedorahosted.org/spacewalk/wiki/GitGuide#BuildingTestRPMs)
* [tito github repo](https://github.com/dgoodwin/tito)
* [RPM Packaging Guide](https://rpm-packaging-guide.github.io/)
* [Fedora Packaging Guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/)
108 changes: 26 additions & 82 deletions docs/candlepin/developer_deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: Developer Deployment

## Operating System
Any flavor of Linux should be acceptable for development, but all of the instructions below are written
for Fedora 35 Workstation. You may need to make slight changes to the package names, depending on what is
for Fedora 43 Workstation. You may need to make slight changes to the package names, depending on what is
available from your system's package repos, and your specific system configuration.

## Getting the Source
Expand All @@ -28,7 +28,7 @@ permission to do so).
$ git clone [email protected]:candlepin/candlepin.git
```

For more information on working with Git, checkout the [Spacewalk](https://fedorahosted.org/spacewalk/) [GitGuide](https://fedorahosted.org/spacewalk/wiki/GitGuide).
For more information on working with Git, see the [Pro Git book](https://git-scm.com/book/en/v2), the [official Git documentation](https://git-scm.com/docs), and [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow).


## Vagrant
Expand All @@ -39,7 +39,8 @@ way to do work on Candlepin, as it helps ensure everyone is working with the sam

1. Install libvirt, Vagrant, Ansible, and the required vagrant plugins
```console
$ sudo dnf install @virtualization vagrant vagrant-libvirt vagrant-sshfs vagrant-hostmanager ansible
$ sudo dnf install @virtualization vagrant ansible libvirt-devel gcc make ruby-devel
$ vagrant plugin install vagrant-libvirt vagrant-sshfs vagrant-hostmanager
```

1. Enable the libvirtd and virtnetworkd services
Expand All @@ -66,25 +67,6 @@ way to do work on Candlepin, as it helps ensure everyone is working with the sam
Candlepin can be deployed following the instructions in the [Deploying Candlepin](#deploying-candlepin)
section.

### Post-setup Steps

Note that while Vagrant makes setting up the environment easier, some elements of the user space may not
be fully configured:

* Git configuration is not copied into the Vagrant box

You will need to manually configure your git e-mail address and name in the Vagrant box.
This step may be omitted, but you will be forced to drop out of the Vagrant box to commit
or push changes.

These steps only need to be performed after initially bringing up the box for the first time, or if the box
is ever recreated after destroying it.

These may eventually be resolved in future versions of the Ansible roles responsible for provisioning the
Vagrant boxes.



## Local Development
If you are unable or unwilling to use the Vagrant box for development tasks, you can, instead, set up your
local environment for Candlepin development. Note that some Candlepin dependencies may not be available from
Expand All @@ -94,49 +76,26 @@ manually resolve the conflict.
1. **Install and configure core dependencies**

```console
$ sudo dnf install gcc make java-1.8.0-openjdk-devel java-11-openjdk-devel jss tomcat gettext openssl
$ sudo dnf install gcc make tomcat gettext openssl
$ sudo dnf install adoptium-temurin-java-repository
$ sudo fedora-third-party enable
$ sudo dnf install temurin-17-jdk
```
By default, the JAVA_HOME environment variable is not setup during this install. This should be configured
to point to the home directory for the "active" JVM (Java 11 in most cases, Java 8 for some older
Candlepin branches).
to point to the home directory for the "active" JVM (Java 17).

On systems where Alternatives is available and configured (as is the case on Fedora 34), this should point
to the Alternatives-managed JDK directory:
On systems where Alternatives is available and configured (as is the case on Fedora 43), this should point
to the active JDK directory. A reliable way to derive this is from the `javac` path:

```console
$ echo 'export JAVA_HOME="/var/lib/jvm/java"' >> ~/.bashrc
$ export JAVA_HOME="$(dirname "$(dirname "$(readlink -f "$(command -v javac)")")")"
$ echo "export JAVA_HOME=\"$JAVA_HOME\"" >> ~/.bashrc
```

If Alternatives is not installed or enabled, JAVA_HOME will need to be configured to point to the explicit
JDK directory as needed.


1. **Install Ruby and Ruby gems**

Candlepin currently requires Ruby 2.4 to run its spec test suite (rspec), which is unfortunately
no longer available through the standard package repos in Fedora 34. For this reason, and to avoid
conflicts with various gems, we highly recommend using [RVM](http://rvm.io) to install and manage Ruby
and its gems.

Instructions for installing RVM are available on the [RVM](http://rvm.io) website (<http://rvm.io>).

Warning: Do not install RVM, Ruby, or the necessary gems as root
{:.alert-bad}

Once RVM is installed, install Ruby 2.4 via rvm:

```console
$ rvm install ruby-2.4
```

Finally, install bundler so we can install the required gems:

```console
$ gem install bundler
$ bundle install
```


1. **Set up PostgreSQL**

PostgreSQL is the recommended database solution for Candlepin. PostgreSQL 9.6 is required at minimum, but
Expand Down Expand Up @@ -332,8 +291,8 @@ and some capabilities:

# Running Tests

Candlepin provides two tests suites for proper functionality and stability: unit tests and specification
tests, via JUnit and rspec, respectively. Whenever changes are made to Candlepin, both of these suites
Candlepin provides two test suites for proper functionality and stability: unit tests and specification
tests, via JUnit. Whenever changes are made to Candlepin, both of these suites
should be run to verify existing functionality has not be affected by the changes, and new tests should be
added to each suite as appropriate for the change.

Expand Down Expand Up @@ -365,31 +324,32 @@ $ ./gradlew test --tests "JobManagerTest.jobStatusFound"

## Specification Tests

Specification tests are run through rspec, and can be invoked through Gradle with the `rspec` task from the
Specification tests are run on the JVM and can be invoked through Gradle with the `spec` task from the
root of the Candlepin repository.

```console
$ ./gradlew rspec
$ ./gradlew spec
```

This will run the entire spec test suite, and write the results to the console. To run tests for a specific
spec test suite, the `--spec` option can be used with the partial file name of the spec file to run, without
the "_spec.rb" suffix.
This will run the entire spec test suite and write the results to the console. To run tests for a specific
spec test suite, the `--tests` option can be used with a suite identifier (for example, a partial suite name).

For example, to run the tests in the activation_key_spec.rb file, the following command can be used:
For example, to run the tests for the ActivationKeySpecTest suite, the following command can be used:

```console
$ ./gradlew rspec --spec activation_key
$ ./gradlew spec --tests ActivationKeySpecTest
Or you can use wildcards, but they must be in quotes:
$ ./gradlew spec --tests "ActivationKey*"
```

Individual tests or groups of tests within a given spec file can be run using the `--test` option and
Individual tests or groups of tests within a given spec file can be run using the `--tests` option and
providing a string to match against the name of the desired tests.

For instance, to run the tests in the activation_key_spec file containing the word "updating", the following
For instance, to run the tests in the ActivationKeySpecTest file containing the word "authorized", the following
command can be used:

```console
$ ./gradlew rspec --spec activation_key --test 'updating'
$ ./gradlew spec --tests "ActivationKeySpecTest.*authorized*"
```


Expand Down Expand Up @@ -427,19 +387,3 @@ 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:

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

You need to clear your journal:

```console
$ rm -rf /var/lib/candlepin/hornetq*
```

22 changes: 11 additions & 11 deletions docs/candlepin/developers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ which stores all the Checkstyle configuration.
Also see the [Java Coding Conventions](java_coding_conventions.html)

### Python
For Python, stick to the guidelines in [PEP8](http://legacy.python.org/dev/peps/pep-0008/).
For Python, stick to the guidelines in [PEP 8](https://peps.python.org/pep-0008/).
Also, run `make stylish` to run pep8, pyflakes, pyqver, rpmlint, and a few
subman specific code checks.

Expand Down Expand Up @@ -47,7 +47,7 @@ Commit messages are used for generating changelogs when tagging builds. It may s
to process a few hundred lines it's very helpful if they're typo free, changelog friendly, and have the
originating task automatically detected.

A general git guide can be found [here](https://fedorahosted.org/spacewalk/wiki/GitGuide).
A general git guide can be found in the [Pro Git book](https://git-scm.com/book/en/v2).

### Commit message format
```text
Expand Down Expand Up @@ -165,12 +165,12 @@ codebase.
```console
$ ./gradlew test --tests EntitlementCuratorTest
```
* Functional rspec tests (from <project root>/server directory):
* Specification tests:

```console
$ ./gradlew rspec
$ ./gradlew spec
```
* The safest bet, in addition to rspec, is to run check (includes all lint tasks, test, validate_translation) before committing:
* The safest bet, in addition to spec, is to run check (includes all lint tasks, test, validate_translation) before committing:

```console
$ ./gradlew check
Expand All @@ -185,7 +185,7 @@ wrong you can end up with an un-maintainable mess. Look for good examples,
experiment, chat with the team, and in general just try to leverage this when
possible. We're all still learning how this works. :)

In the Java unit tests this is accomplished with [Mockito](http://code.google.com/p/mockito/).
In the Java unit tests this is accomplished with [Mockito](https://site.mockito.org/).

In subscription-manager and python-rhsm we use the python-mock module: <http://www.voidspace.org.uk/python/mock/>

Expand Down Expand Up @@ -222,8 +222,9 @@ See [the debugging with wireshark page](debugging_with_wireshark.html)
# Tips

## Auto-Generating candlepin.conf
Buildr can auto-generate candlepin.conf for you. This is very useful when you
are constantly switching between databases. See [the AutoConf page](auto_conf.html).
The Candlepin deploy script can generate `candlepin.conf` for you, which is useful when switching
between databases/environments. See [Developer Deployment](developer_deployment.html) for the `-a`
option, and see [the AutoConf page](auto_conf.html) for legacy Buildr-based workflows.

## Backup / Restore A Database
It can be helpful for developers to save a postgresql database for later use
Expand All @@ -236,10 +237,10 @@ $ pg_dump -U candlepin candlepin > candlepindb.sql
To restore an old database:

```console
$ sudo service tomcat6 stop
$ sudo systemctl stop tomcat
$ dropdb -U candlepin candlepin && createdb -U candlepin candlepin
$ psql -U candlepin candlepin < ~/src/candlepin/candlepindb.sql
$ buildconf/scripts/deploy -g -t
$ ./bin/deployment/deploy -g -t -a
```

## Debugging with Tomcat
Expand All @@ -250,7 +251,6 @@ To enable remote debugging in Tomcat, you must pass the JVM values telling it to

```
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000 # for Java 11+
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000 # for Java 8 or earlier
```
Now you will be able to connect a debugger to port 8000.

Expand Down
14 changes: 6 additions & 8 deletions docs/candlepin/java_coding_conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,14 @@ addressed by this document should follow the official [Code Conventions for the
Java Programming Language](http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html).

Conventions specific to Candlepin have been primarily drawn from the
conventions imposed by
[Spacewalk](https://fedorahosted.org/spacewalk/wiki/JavaCodingConventions), or
have been invented to accommodate matters of internal style and practicality.
conventions imposed by upstream projects, and have been invented to accommodate matters of internal style
and practicality.
To help people conform to the document conventions, we have integrated
[checkstyle](http://checkstyle.sourceforge.net/) into our build tree.
[checkstyle](https://checkstyle.sourceforge.io/) into our build tree.

The checkstyle configuration file, `buildconf/checkstyle.xml`, is our
definitive style guide source. The conventions here should be putting
those conventions into english and for things checkstyle can't check.
[Configuration Checkstyle](checkstyle.html)
The checkstyle configuration file, `config/checkstyle/checkstyle.xml`, is our definitive style guide source.
The conventions here should be putting those conventions into english and for things checkstyle can't check.
See [Checkstyle configuration](checkstyle.html).

## Brackets
All left brackets should be the end of the line and all right brackets should be alone on the line.
Expand Down