Skip to content

Building and Deploying SwingSet

Jump to bottom
Brian Pangburn edited this page Mar 14, 2024 · 18 revisions

Introduction

These instructions are based on running Java in a Linux environment so the instructions may be a bit different on another OS, especially the first part to set the java/javac versions and $JAVA_HOME environment variable.

Java Version

First, we want to make sure we're running Java 9+. I try to stay with LTS releases so I'm using Java 11. Note that I would use Java 17 except my OS is still using Apache Maven 3.6.3, which does not appear to be compatible with Java 17.

If you'd like to install a newer version of Maven, this guide has good instructions for Debian-based Linux distributions. https://linuxize.com/post/how-to-install-apache-maven-on-debian-10/

As of 2021-11-18, we're still compiling for a Java 8 target, but we use the Java 9+ JavaDoc compiler as the results are much nicer and we have some JavaDoc markup that is not supported in Java 8.

Linux allows you to have a separate versions of java and javac so I use update-java-alternatives which keeps them aligned. E.g.

user@domain:~$ sudo update-java-alternatives -l
java-1.11.0-openjdk-amd64      1111       /usr/lib/jvm/java-1.11.0-openjdk-amd64
java-1.17.0-openjdk-amd64      1711       /usr/lib/jvm/java-1.17.0-openjdk-amd64
java-1.8.0-openjdk-amd64       1081       /usr/lib/jvm/java-1.8.0-openjdk-amd64

user@domain:~$ sudo update-java-alternatives -s java-1.11.0-openjdk-amd64

user@domain:~$ java -version
openjdk version "11.0.11" 2021-04-20
OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04)
OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode)

user@domain:~$ javac -version
javac 11.0.11

If you get an error such as update-java-alternatives: command not found you may need to give the full path (normally /usr/sbin/update-java-alternatives)

If you see a warning of update-alternatives: error: no alternatives for mozilla-javaplugin.so it should be safe to ignore for SwingSet.

Note that we could use sudo update-alternatives --config java, but that only changes the java version, not the javac version. update-alternatives would have to be run for each Java component.

Now we want a $JAVA_HOME environment variable that points to our JDK:

user@domain:~$ export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

user@domain:~$ echo $JAVA_HOME
/usr/lib/jvm/java-11-openjdk-amd64

If you want to set $JAVA_HOME permanently, this link is a solid guide: https://www.linuxfordevices.com/tutorials/linux/set-the-java-home-variable

Plugin and Dependency Checks

Now we want to make sure that our Maven plugins and dependencies are up-to-date. Navigate to the top-level SwingSet folder and run the commands to check for newer plugins and dependencies across all SwingSet projects:

user@domain:~$ cd git/swingset/
user@domain:~/git/swingset$ mvn versions:display-property-updates
user@domain:~/git/swingset$ mvn versions:display-plugin-updates
user@domain:~/git/swingset$ mvn versions:display-dependency-updates

Each command will generate a moderate amount of output, but for each POM/component you want to look for: All plugins with a version specified are using the latest versions. Or: No dependencies in Dependencies have newer versions.

Note that this is not bulletproof. For example, at the time of writing the Dependency Check Maven Plugin in our POMs was 6.4.1, but checking the Maven Repository at https://mvnrepository.com/artifact/org.owasp/dependency-check-maven showed that 6.5.0 was available.

Vulnerability Tests

Next we want to run the Dependency Check Maven Plugin, which will output an html report, dependency-check-report.html, in the 'target' subfolder of each project/subproject. If all dependencies and plugins are up-to-date then there may not be much that can be done about any outstanding vulnerabilities. I'm generally less concerned about vulnerabilities in the POM dependencies than those in any SwingSet or SwingSet Demo dependency jars (e.g., GlazedLists, Log4J, JdbcRowSetImpl, H2 database).

In order to check the demo the latest SwingSet SNAPSHOT will need to be installed in the local Maven repository.

user@domain:~$ cd git/swingset/swingset
user@domain:~/git/swingset/swingset$ mvn clean install -Prelease,java-9-plus
user@domain:~/git/swingset/swingset$ cd..

Now from the parent SwingSet folder we can run the Dependency Check.

user@domain:~/git/swingset$ mvn org.owasp:dependency-check-maven:check

Note that if the command line interface (CLI) is showing an older version of the OWASP Dependency-Check an easy fix is to add the version number to the command: mvn org.owasp:dependency-check-maven:7.3.2:check A last resort fix is to delete the "/.m2/repository" folder. Don't delete the entire ".m2" folder or settings.xml will be lost.

Encryption Keys

Make sure that the SwingSet public/private keys are setup on the local machine with user@domain:~$ gpg --list-keys.

If not dump them to a text file (e.g. swingsetkeys.txt) and import them using user@domain:~$ gpg --import ./tmp/swingsetkeys.txt. You will need the passphrase before importing the keys. Make sure to permanently delete any temporary text files created for importing the keys.

Make sure that settings.xml is saved in the .m2/ folder of the user's home folder. This will have sensitive info such as the passphrase for the gpg signing key and the jira/sonatype login for deploying the Maven artifacts.

Housekeeping

Before making a release:

  1. Make sure the CHANGELOG.txt and CHANGELOG-POMS.txt files are up-to-date (including the release date).
  2. Review all POMs (3) to make sure that "-SNAPSHOT" has been removed from the variable and for swingset-demo from both and <version.swingset>.
  3. Check GitHub for any outstanding pull requests on the branch to be used for the release. Generally releases are done from "master" or "X.Y.Z-SNAPSHOT".
  4. Make sure that your local machine is using the proper branch (in Eclipse, right-click project, Team, Switch To).
  5. Fetch and pull any updates for the branch.

Compile, Package, & Install into Local Maven Repository

  1. From the home folder, move to the main swingset project folder (not the parent folder): user@domain:~$ cd git/swingset/swingset/.
  2. Perform a clean/verify with Maven, which will create the project jars and sign the files with the GPG key: user@domain:~$ mvn clean verify -Prelease,java-9-plus. If you do not have the GPG key for SwingSet, then it's probably better to use package instead of verify to skip the signing. Without the GPG key you won't be able to do a full deployment to the Sonatype nexus repository manager.
  3. Presuming there are no errors for step 2, install SwingSet into your local Maven repository so that the demo will see it during compilation: user@domain:~$ mvn install -Prelease,java-9-plus
  4. From the home folder, move to the swingset demo project folder: user@domain:~$ cd git/swingset/swingset-demo/.
  5. Perform a clean/verify with Maven, which will create the project jars and sign the files with the GPG key: user@domain:~$ mvn clean verify -Prelease.

Tag Version on GitHub from Eclipse

  1. Make sure that the correct branch (usually "master") is loaded into Eclipse and up-to-date.
  2. Right click on "swingset-parent" and select Team->Advanced->Create Tag.
  3. For "Tag name:" enter swingset-x.y.z (substituting version number).
  4. For "Tag message" enter SwingSet x.y.z as released yyyy-mm-dd (substituting version number and date).
  5. Press "Create Tag and Start Push".

Release Artifact on Sonatype

  1. From the home folder, move to the main swingset project folder (not the parent folder): user@domain:~$ cd git/swingset/swingset/.
  2. Perform a clean/deploy with Maven, which will create the project jars, sign the files with the GPG key, and attempt to deploy them to the Sonatype nexus repository manager: user@domain:~$ mvn clean deploy -Prelease,java-9-plus.
  3. Log into the repository manager at: https://oss.sonatype.org/#welcome and log in.
  4. Select "Staging Repositories" from the menu on the left.
  5. Check the box for the entry with Status of "closed" and Description of "com.nqadmin.swingset:swingset:x.y.z" and press the "Release" button. When prompted you can add a description such as "swingset-4.0.5 artifact release" and then press "Confirm".
  6. If you see a Repository with a description such as "Implicitly created (auto staging)." you can select it and press "Drop".

Add Release on GitHub

  1. Log in to GitHub.
  2. Navigate to the Release page: https://github.com/bpangburn/swingset/releases
  3. Copy the text from the prior release.
  4. Right-click on the Draft a new release button and open it in a new tab.
  5. Select the appropriate tag.
  6. Paste in the prior release contents and update accordingly (e.g., copy latest CHANGELOG entries, update the links to point at the latest release).
  7. Attach the binary files for the release:
git/swingset/swingset/target/:

    swingset-x.y.z-javadoc.jar
    swingset-x.y.z-sources.jar
    swingset-x.y.z.jar

git/swingset/swingset-demo/target/:

    swingset-demo-x.y.z-jar-with-dependencies.jar
    swingset-demo-x.y.z-sources.jar
  1. Press the Publish release button.

Clean Up

After making a release:

  1. Make a new SNAPSHOT branch on GitHub.
  2. Switch to the new SNAPSHOT locally.
  3. Increment the version number and append "-SNAPSHOT" to the variable in all POMs (3). Make the same change to the <version.swingset> variable in the swingset-demo POM.
  4. Add a block for the next release to the top of the CHANGELOG.txt file with a release date of "TBD".
  5. Delete the prior version snapshot branch on GitHub.
Clone this wiki locally