Publishing a Compodoc Site to Nexus

David Hutchison — Wed, 27 May 2020 22:24:00 +0000

Recently I have been looking at Compodoc for generating documentation sites for Angular projects. Some of these projects are for libraries that will be reused elsewhere, so this documentation requires to be published somewhere.

The libraries are published as NPM modules to a Sonatype Nexus instance, so it would be ideal if the documentation could be published to the same place.

Nexus has a Raw Repository type which can be used for hosting static websites. The linked page includes details of how to configure a repository, how to publish to it from Maven, and using curl to upload single files using HTTP requests.

Based on this curl approach I have put together a bash script below that:

has a number of configuration options for the user, nexus server, repository name, and documentation directory to upload
prompts for the password for the user to use
uses the git repository name as a subdirectory to store items in within the nexus repository, so that the same nexus repository could be used as a central location for generated documentation for multiple projects
iterates through every file in the configured documentation directory and uploads it to nexus

Once this script runs, you will be able to see the contents of the site in the browse view for the repository.

Clicking on the index.html file will show the details, including the direct path to the artefact.

This will be the URL that your documentation site will be available at. The script below assumes there will be an index.html file and outputs the direct URL to this resource.

#!/bin/bash

# Configure username to use. The password will be prompted for later.
USER=admin

# The URL for the Nexus server
NEXUS_SERVER=https://nexus.example.com
# The name of the raw repository
REPOSITORY_NAME=documentation
# Each project will have its own directory based on the git repository name
GIT_REPO_NAME=$(basename -s .git $(git config --get remote.origin.url))

# Make our base Nexus repository directory URL
DEST_REPO_DIRECTORY="${NEXUS_SERVER}/repository/${REPOSITORY_NAME}/${GIT_REPO_NAME}"

# The directory to get the contents of to upload
LOCAL_DOCS=./documentation

# Prompt for the user password to use
read -s -p "Password for $USER: " PASS

# Find all the files in the directory and upload them. 
# This may have issues if you had spaces in filenames, but 
# generated documentation produced by compodoc doesn't

for file in $(find "$LOCAL_DOCS" -type f -print); do

    # Need to trim the local documentation directory part off the string
    destination_file="${file/$LOCAL_DOCS/}"

    # Upload the file
    # This uses verbose logging, you will want to reduce the logging here
    # if using this in a production environment
    curl -v --user "${USER}:${PASS}" --upload-file "$file" "${DEST_REPO_DIRECTORY}${destination_file}"

done

echo "If no errors were reported above, your documentation site will be available at ${DEST_REPO_DIRECTORY}/index.html"

Restricting Software Libraries in Nexus

David Hutchison — Thu, 12 Mar 2020 20:29:00 +0000

As part of looking in to controlling the third party libraries which could be included for use by a project, I wondered if it was possible to effectively apply an approved whitelist at the Sonatype Nexus level. This would only be effective if developers and CI tools are restricted in their web access and cannot contact the central artefact repositories directly, and so are forced to use Nexus as a mirror.

It turns out that this is possible, and the Nexus documentation is pretty good if you know the pieces of the puzzle that need to be joined together to make this work. Roles, which can be assigned to specific users or an anonymous user, are made up of privileges. Privileges can include Content Selectors to restrict the results which are returned. When combining these things, we can effectively build a whitelist. As this approach is role based, different rules can be used depending on who the caller is.

While the examples in this post are for applying this to Maven dependencies, the same concept can be used with other repository types supported by Nexus such as NPM.

Content Selectors

Content selectors provide a means for you to select specific content from all of your content. The content you select is evaluated against expressions written in CSEL (Content Selector Expression Language).

For example, to configure a selector for only Apache Software Foundation libraries, we would use these settings.

There are a variety of options which can be used for making the filter conditions, based on the repository type and the type of artifact.

Path based searches can be used for all repository formats.

format == "maven2" and path =^ "/org/apache/"

Maven format repositories can use additional filters based on the Maven coordinates.

format == "maven2" and coordinate.groupId == "org.apache"

The options which are available as properties of “coordinate” are not well documented, but are included in the code as the values for the “VALID_REFERENCES” constant in CselValidator.java.

Privileges

A Repository Content Selector Privilege is created using this Content Selector. This means that for each Content Selector that is to be added to our whitelist we require a Privilege.

Roles

A role is configured to group privileges together to form a group or permissions which a user can be assigned.

Users

One or many roles can then be assigned to a user, including to the anonymous user.

Testing the Implementation

For simplicity of a test, this was tested using cURL to verify that a whitelisted Maven artefact could be downloaded, while an item not in the list could not.

An approved item returns an HTTP 200 (OK) response.

MacBook:payara dhutchison$ curl -I https://nexus.lan/repository/maven-central/org/apache/ant/ant/1.10.5/ant-1.10.5.pom
HTTP/2 200 
content-security-policy: sandbox allow-forms allow-modals allow-popups allow-presentation allow-scripts allow-top-navigation
content-type: application/xml
date: Tue, 25 Feb 2020 22:10:49 GMT
etag: "1d48137927c0900a9d8e85e640b6cb74"
last-modified: Tue, 10 Jul 2018 04:54:03 GMT
server: Nexus/3.20.1-01 (OSS)
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
content-length: 10470

Trying the same test for an item not in our approved whitelist will fail with an HTTP 401 (Unauthorized) response.

MacBook:payara dhutchison$ curl -I https://nexus.lan/repository/maven-central/xalan/xalan/2.7.2/xalan-2.7.2.pom
HTTP/2 401 
content-security-policy: sandbox allow-forms allow-modals allow-popups allow-presentation allow-scripts allow-top-navigation
date: Tue, 25 Feb 2020 22:13:08 GMT
server: Nexus/3.20.1-01 (OSS)
www-authenticate: BASIC realm="Sonatype Nexus Repository Manager"
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
content-length: 0