Configure an agent with Maven repository access

In order for Moderne to retrieve your Lossless Semantic Tree (LST) or recipe artifacts, the agent needs to be configured to talk to your Maven-formatted artifact repositories. This connection also allows Moderne to lookup dependency versions to determine if a new version is available.

There are a variety of services that support Maven-formatted artifact repositories. Some examples include JFrog Artifactory, Sonatype Nexus, and Azure Artifacts.

If your company has a rule that any externally-hosted JARs (e.g., Maven Central) be brought into an internal Maven repository (e.g., Artifactory) and scanned before being used, the instructions in this doc must be followed. Furthermore, please ensure that you point the agent to your internal Maven repository and that the OpenRewrite JARs and dependencies are included in said repository.

This guide will explain how to:

• Configure your artifact service to support LST and recipes artifacts

• Configure the Moderne agent to connect to any service that supports Maven-formatted repositories

Prerequisites

• You might need a username and password for a user that is allowed to resolve artifacts.

In many organizations, artifact resolution is unauthenticated while artifact publishing is authenticated. If artifact resolution is unauthenticated, you may omit the username/password configuration in the Configuration step.

Publishing LST artifacts

Configure the Maven Indexer

In order to publish LST artifacts, the artifact registry must be regularly updated with an index in the Maven Indexer format. The frequency with which the index is updated is an approximation of the time it will take for an LST that is published to your artifact repository to show up in Moderne. You will need to decide where the border is between faster publishing and the load required on your Artifactory instance.

Please follow the below instructions to configure the indexer for your Maven formatted repository:

Artifactory

If you are using Artifactory to publish LST artifacts, it is highly recommended that you follow the instructions in the configuring an agent with Artifactory doc instead as that will result in faster artifact consumption while also avoiding substantial load on your Artifactory instance. The following instructions should only be followed if you can not use AQL for some reason.

In Artifactory, select the Artifactory link on the left nav and then select Maven Indexer under Services:

For a repository to be a source of LSTs, it must be included in the list of repositories that are indexed:

Nexus Repository

Under the administration view, select Tasks on the left nav:

Select Create task and create a Maven - Publish Maven Indexer files task:

Select the repository that will serve LST artifacts and specify a frequency with which this index should be updated:

Publishing recipe artifacts

Recipe artifacts will automatically be picked up by Moderne so long as you set the recipe source flag to true in the below configuration step. These artifacts will be immediately available for deployment to Moderne upon being published.

Configuring the Moderne agent

The following table contains all of the variables/arguments you need to add to your Moderne agent run command in order for it to get LST and recipe artifacts from your Maven formatted repository. Please note that these variables/arguments must be combined with ones found in other steps in the Configuring the Moderne agent guide.

You can configure multiple Maven formatted repositories by including multiple entries, each with a different {index}.

OCI Container

Variables:

• MODERNE_AGENT_MAVEN_{index}_URL – The URL of your Maven repository.

• MODERNE_AGENT_MAVEN_{index}_LOCALREPOSITORY – The path on disk where LST artifacts and Maven index files will be downloaded to. This is on the disk where the agent is being run and not on the Maven instance. Defaults to ~/.moderne-maven

  • LST artifacts are deleted from this location after they are transmitted to Moderne. Index files will remain behind to be used to detect diffs in the artifacts. If changes are discovered, only the incremental diffs will be downloaded (to limit the amount of data being transferred).

  • If multiple Maven repositories are configured on the agent, they must have different MODERNE_AGENT_MAVEN_{index}_LOCALREPOSITORY configured.

• MODERNE_AGENT_MAVEN_{index}_USERNAME – (Optional) The username used to resolve artifacts. Defaults to null.

• MODERNE_AGENT_MAVEN_{index}_PASSWORD – (Optional) The password used to resolve artifacts. Defaults to null.

• MODERNE_AGENT_MAVEN_{index}_RELEASES – (Optional) Specifies whether or not this repository should be searched for releases. Defaults to true.

• MODERNE_AGENT_MAVEN_{index}_SNAPSHOTS – (Optional) Specifies whether or not this repository should be searched for snapshots. Defaults to true.

• MODERNE_AGENT_MAVEN_{index}_ASTSOURCE – (Optional) Specifies whether or not this repository should be searched for LST artifacts. Defaults to true (Note: LSTs used to be called ASTs).

• MODERNE_AGENT_MAVEN_{index}_RECIPESOURCE – (Optional) Specifies whether or not this repository should be searched for recipe jars. Defaults to true.

If you want to configure a Moderne DevCenter, you will need to ensure that you have exactly one Maven repository configured with RECIPESOURCE set to true. (It is fine to have this same Maven repository configured in multiple agents.)

• MODERNE_AGENT_MAVEN_{index}_SKIPSSL – (Optional) Whether or not to skip SSL/TLS verification for calls from the agent to this Maven repository. This must be set to true if you use a self-signed SSL/TLS certificate. Defaults to false.

Example:

docker run \
# ... Existing variables
-e MODERNE_AGENT_MAVEN_0_URL=https://myartifactory.example.com/artifactory/libs-releases-local \
-e MODERNE_AGENT_MAVEN_0_LOCALREPOSITORY=~/.moderne-maven \
-e MODERNE_AGENT_MAVEN_0_USERNAME=admin \
-e MODERNE_AGENT_MAVEN_0_PASSWORD=password \
# ... Additional variables

Executable JAR

Arguments:

• --moderne.agent.maven[{index}].url – The URL of your Maven repository.

• --moderne.agent.maven[{index}].localRepository – The path on disk where LST artifacts and Maven index files will be downloaded to. This is on the disk where the agent is being run and not on the Maven instance. Defaults to ~/.moderne-maven

  • LST artifacts are deleted from this location after they are transmitted to Moderne. Index files will remain behind to be used to detect diffs in the artifacts. If changes are discovered, only the incremental diffs will be downloaded (to limit the amount of data being transferred).

  • If multiple Maven repositories are configured on the agent, they must have different MODERNE_AGENT_MAVEN_{index}_LOCALREPOSITORY configured.

• --moderne.agent.maven[{index}].username – (Optional) The username used to resolve artifacts. Defaults to null.

• --moderne.agent.maven[{index}].password – (Optional) The password used to resolve artifacts. Defaults to null.

• --moderne.agent.maven[{index}].releases – (Optional) Specifies whether or not this repository should be searched for releases. Defaults to true.

• --moderne.agent.maven[{index}].snapshots – (Optional) Specifies whether or not this repository should be searched for snapshots. Defaults to true.

• --moderne.agent.maven[{index}].astSource – (Optional) Specifies whether or not this repository should be searched for LST artifacts. Defaults to true (Note: LSTs used to be called ASTs).

• --moderne.agent.maven[{index}].recipeSource – (Optional) Specifies whether or not this repository should be searched for recipe jars. Defaults to true.

If you want to configure a Moderne DevCenter, you will need to ensure that you have exactly one Maven repository configured with recipeSource set to true. (It is fine to have this same Maven repository configured in multiple agents.)

• --moderne.agent.maven[{index}].skipSsl – (Optional) Whether or not to skip SSL/TLS verification for calls from the agent to this Maven repository. This must be set to true if you use a self-signed SSL/TLS certificate. Defaults to false.

Example:

java -jar moderne-agent-{version}.jar \
# ... Existing arguments
--moderne.agent.maven[0].url=https://myartifactory.example.com/artifactory/libs-releases-local \
--moderne.agent.maven[0].localRepository=~/.moderne-maven \
--moderne.agent.maven[0].username=admin \
--moderne.agent.maven[0].password=password \
# ... Additional arguments