From 5b15dffd7f380a95b559a7cc08975d1d9079ba30 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Wed, 24 Jun 2026 15:55:11 -0400 Subject: [PATCH 1/2] CGRepo for Java - Global config Signed-off-by: s-stumbo --- .../libraries/java/global-configuration.md | 151 +++++++----------- 1 file changed, 59 insertions(+), 92 deletions(-) diff --git a/content/chainguard/libraries/java/global-configuration.md b/content/chainguard/libraries/java/global-configuration.md index d1983725bc..2842562ee4 100644 --- a/content/chainguard/libraries/java/global-configuration.md +++ b/content/chainguard/libraries/java/global-configuration.md @@ -3,8 +3,8 @@ title: "Global configuration" linktitle: "Global configuration" description: "Configuring Chainguard Libraries for Java in your organization" type: "article" -date: 2025-03-25T08:04:00+00:00 -lastmod: 2025-04-07T14:42:00+00:00 +date: 2026-06-24T08:04:00+00:00 +lastmod: 2026-06-24T14:42:00+00:00 draft: false tags: ["Chainguard Libraries", "Java"] images: [] @@ -24,39 +24,48 @@ Repository](https://www.sonatype.com/products/sonatype-nexus-repository). The repository manager acts as a single point of access for developers and development tools to retrieve the required libraries. -At a high level, adopting the use of Chainguard Libraries consists of the -following steps: - -* Add Chainguard Libraries as a remote repository for library retrieval. -* Configure the Chainguard Libraries repository as the first choice for any - library access. This ensures that any future requests of new libraries access - the version supplied by Chainguard. Typically this is accomplished by creating a - group repository or virtual repository that combines the repository with other - external and internal repositories. - -Additional steps depend on the desired insights and can include the following +The recommended approach is to use the [upstream +fallback](/chainguard/libraries/overview/#upstream-fallback-and-controls) +feature of Chainguard Repository, which allows you to configure your repository +manager with a single upstream pointed at `https://libraries.cgr.dev/java/`. The +Chainguard Repository handles fallback and policy enforcement; your repository +manager handles local caching and access control. Chainguard also retrieves +packages from the public Maven Central repository on your behalf when upstream +fallback is enabled. This includes protections such as malware scanning and a +cooldown period for newly published packages. + +At a high level, adopting the use of Chainguard Libraries consists of the following steps: + +* Configure your environment to use `https://libraries.cgr.dev/java/` + as the single upstream source for Java package retrieval. This can be done + either: + * As a remote repository in your repository manager, or + * Directly in your Java build configuration (for example, Maven or Gradle). +* Additional steps depend on your specific environment and preferences, and can include the following optional measures: + * Remove all cached artifacts for Maven Central. This step ensures that any libraries you pull are from Chainguard Libraries, and not existing cached artifacts from upstream. + * Remove any repositories that are no longer desired or necessary, depending on your organization's preferences. -* Remove all cached artifacts in the proxy repository of Maven Central and other - repositories. This step allows you to validate which libraries are not - available from Chainguard Libraries and proceed with potential next steps with - Chainguard and your own development efforts. -* Remove any repositories that are no longer desired or necessary. Depending on - your library requirements this step can result in removal of some proxy - repositories or even removal of all proxy repositories. - -Adopting the use of a repository manager is the recommended approach, however if -your organization does not use a repository manager, you can still use -Chainguard Libraries. All access to the Chainguard Libraries repository is then -distributed across all your build platforms and therefore more complex to -configure and control. Refer to the [direct access documentation for build +This page explains how to use Chainguard Libraries for Java with a repository +manager. If your organization does not use a repository manager, you can pull +directly from Chainguard. Refer to the [direct access documentation for build tools](/chainguard/libraries/java/build-configuration/#direct-access) for more information. -### Considerations for fallback approach +### Manually managing fallback +Chainguard recommends using the Chainguard Repository's built-in [upstream +fallback](/chainguard/libraries/overview/#upstream-fallback-and-controls) +rather than configuring a public registry fallback in your repo manager. +Configuring your own fallback bypasses the protection that the Chainguard +Repository provides. + +However, if upstream fallback is not enabled or you prefer to manage your own fallback +ordering, you can configure `https://libraries.cgr.dev/java/` as a remote +repository alongside your Maven upstream, and combine them in a virtual or group +repository with Chainguard as the first priority. The per-tool instructions on +this page follow this pattern. -Before configuring your repo manager, consider how you want to handle packages that aren't -yet available in the Chainguard Libraries repository. If you configure a fallback to Maven Central, packages sourced from that registry are not covered by Chainguard's +Before configuring your own fallback, consider how you want to handle packages that aren't yet built by Chainguard. If you configure a fallback to Maven Central, packages sourced from that registry are not covered by Chainguard's malware-resistance guarantees. See the [fallback approaches](/chainguard/libraries/quickstart/#artifact-manager-recommended) described in the Chainguard Libraries quick start for guidance on choosing the right approach for your environment. @@ -73,8 +82,7 @@ by defining multiple upstream repositories. ### Initial configuration -Use the following steps to add a repository with the Maven Central Repository -and the Chainguard Libraries for Java repository as Maven upstream repositories. +Use the following steps to set up a repository in Cloudsmith to access Chainguard Java Libraries via the Chainguard Repository. Configure a `java-all` repository: @@ -88,19 +96,6 @@ Configure a `java-all` repository: infrastructure. 1. Click **+Create Repository**. -Configure an upstream proxy for the Maven Central Repository: - -1. Click the name of the new `java-public` repository on the repositories - page to configure it. -1. Click the **Upstreams** tab, then click **+Add Upstream Proxy**. -1. Configure an upstream proxy with the format **Maven**. -1. Configure another upstream proxy with the following: - * **Name**: `java-public` - * **Priority**: `2` - * **Upstream URL**: `https://repo1.maven.org/maven2/` - * **Mode**: Cache and Proxy -1. Click **Create Upstream Proxy**. - Configure an upstream proxy for the Chainguard Libraries for Java repository: 1. Click the name of the new `java-chainguard` repository on the repositories @@ -116,6 +111,8 @@ Configure an upstream proxy for the Chainguard Libraries for Java repository: 1. Click **Create Upstream Proxy**. 1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details. +If you are manually configuring fallback, you can add an additional upstream proxy for the public Maven Central repository with a lower priority than `java-chainguard`. + Use this setup for initial testing with Chainguard Libraries for Java. For production usage, add the `java-chainguard` upstream proxy to your production repository. @@ -151,7 +148,7 @@ are tagged with the name of the upstream proxy. ## Google Artifact Registry -[Google Artifact Registry](https://cloud.google.com/artifact-registry) supports +[Google Artifact Registry (GAR)](https://cloud.google.com/artifact-registry) supports the Maven format for hosting artifacts in **Standard** repositories and proxying artifacts from public repositories in **Remote** repositories. Use **Virtual** repositories to combine them for consumption with Maven and other build tools. @@ -161,9 +158,7 @@ point for more details. ### Initial configuration -Use the following steps to add the Maven Central Repository and the Chainguard -Libraries for Java repository as remote repositories and combine them as a -virtual repository: +Use the following steps to set up a repository in GAR to access Chainguard Java Libraries via the Chainguard Repository. 1. Log in to the Google Cloud console as a user with administrator privileges. 1. Navigate to your project and find the **Artifact Registry** with the search. @@ -180,22 +175,10 @@ value as retrieved with chainctl](/chainguard/libraries/access/): 1. Set the **Secret** value to the password from your `chainctl` output. 1. Click **Create secret**. -Navigate to Artifact Registry and select **Repositories** in the left hand -navigation under the **Artifact Registry** label to configure a remote -repository for the Maven Central Repository: +Navigate to Artifact Registry. In the left hand navigation under Artifact Registry, select **Repositories**. Configure a remote +repository for Chainguard Libraries for Java: 1. Click **Create a Repository** (or the **+** button). -1. Configure the repository: - * **Name**: `java-public` - * **Format**: Maven - * **Mode**: Remote - * **Remote repository source**: Maven Central - * **Location type > Region**: Select a region. -1. Click **Create**. - -Configure a remote repository for the Chainguard Libraries for Java repository: - -1. Click **+** to add another repository. 1. Configure the repository: * **Name**: `java-chainguard` * **Format**: `Maven` @@ -210,6 +193,8 @@ Configure a remote repository for the Chainguard Libraries for Java repository: 1. Click **Create**. 1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details. +If you are manually managing fallback, you can configure an additional remote repository for the public Maven Central with lower priority. + Combine the repositories in a new virtual repository: 1. Click the **+** button to add another repository. @@ -221,12 +206,9 @@ Combine the repositories in a new virtual repository: 1. Use the **Browse** button to locate and select the `java-chainguard` repository as **Repository 1** and set the **Policy name 1** to `java-chainguard`. -1. Use the **Browse** button to locate and select the `java-public` repository - as **Repository 1** and set the **Policy name 1** to `java-public`. +1. If you are using the remediated repository or manually configuring fallback to the public Maven repository, use the **Browse** button to locate and select each repository. 1. Under **Virtual upstream repositories**, click **Add upstream repository**. -1. Set the **Priority** value for the `java-chainguard` policy name to a higher - value than the `java-public` priority value. - * If you are using the remediated repository, add the `java-chainguard-remediated` repository and ensure it is the first in the displayed list. If not, ensure the `java-chainguard` repository is first. +1. Set the **Priority** values for the repositories. The priority order should be: `java-chainguard-remediated`, `java-chainguard`, then if you are manually configuring fallback to public Maven, `java-public` last. 1. Under **Location type**, choose the same suitable **Region** for your development as configured for the `java-public` repository. 1. Click **Create**. @@ -258,24 +240,12 @@ for more information. ### Initial configuration -Use the following steps to add the Maven Central Repository and the Chainguard -Libraries for Java repository as remote repositories and combine them as a -virtual repository: +Use the following steps to set up a repository in Artifactory to access Chainguard Java Libraries via the Chainguard Repository. 1. Log in as a user with administrator privileges. 1. Click **Administration** in the top navigation bar. 1. Select **Repositories** in the left hand navigation. -Configure a remote repository for the Maven Central Repository: - -1. Click **Create a Repository** and choose the **Remote** option. -1. Configure the repository: - * **Package type**: Maven - * **Repository Key**: `java-public` - * **URL**: `https://repo1.maven.org/maven2/` - * Deactivate **Maven Settings - Handle Snapshots**. -1. Click **Create Remote Repository**. - Configure a remote repository for the Chainguard Libraries for Java repository: 1. Click **Create a Repository** and choose the **Remote** option. @@ -291,6 +261,8 @@ Configure a remote repository for the Chainguard Libraries for Java repository: 1. Click **Create Remote Repository**. 1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details. +If you are manually managing fallback, you can configure an additional remote repository for Maven Central with lower priority. Make sure to deactivate **Maven Settings - Handle Snapshots** in the remote repository. + Combine the repositories in a new virtual repository: 1. Click **Create a Repository** and choose the **Virtual** option. @@ -383,23 +355,15 @@ Libraries for Java repository for production use. ### Initial configuration -For initial testing and adoption it is advised to create a separate proxy +Use the following steps to set up a repository in Sonatype Nexus to access Chainguard Java Libraries via the Chainguard Repository. + +If you are configuring your own fallback in your repo manager, for initial testing it is advised to create a separate proxy repository for the Maven Central Repository, a separate proxy repository -Chainguard Libraries for Java repository, and a separate repository group: +Chainguard Libraries for Java repository, and a separate repository group. 1. Log in as a user with administrator privileges. 1. Click the gear icon in the top navigation bar to access **Server administration**. -Configure a remote repository for the Maven Central Repository: - -1. Select **Repository - Repositories** in the left hand navigation. -1. Click **Create repository**, then select the `maven2 (proxy)` recipe. -1. Configure the repository: - * **Name**: `java-public` - * **Maven 2 - Version policy**: `Release` - * **Proxy - Remote storage**: Add the URL `https://repo1.maven.org/maven2/`. -1. Click **Create repository**. - Configure a remote repository for the Chainguard Libraries for Java repository: 1. Select **Repository - Repositories** in the left hand navigation. @@ -414,6 +378,8 @@ Configure a remote repository for the Chainguard Libraries for Java repository: 1. Click **Create repository**. 1. If you are using the separate repository with remediated Java libraries, repeat the preceding steps to create remote repository named `java-chainguard-remediated` with a URL set to `https://libraries.cgr.dev/java-remediated/`. Use the same authentication details. +If you are manually managing fallback, you can configure an additional `java-public` remote repository for Maven Central with lower priority. + Combine a new repository group and add the repositories: 1. Select **Repository - Repositories** in the left hand navigation. @@ -445,3 +411,4 @@ Use the URL of the repository group, such as configuration](/chainguard/libraries/java/build-configuration/) and build a first test project. In a working setup the `java-chainguard` proxy repository contains all libraries retrieved from Chainguard. + From 17a65a87d29665c5deaf2a62aba75acd90dcb844 Mon Sep 17 00:00:00 2001 From: s-stumbo Date: Tue, 30 Jun 2026 11:44:55 -0400 Subject: [PATCH 2/2] updates Signed-off-by: s-stumbo --- .../libraries/java/global-configuration.md | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/content/chainguard/libraries/java/global-configuration.md b/content/chainguard/libraries/java/global-configuration.md index 2842562ee4..7d48cff9fb 100644 --- a/content/chainguard/libraries/java/global-configuration.md +++ b/content/chainguard/libraries/java/global-configuration.md @@ -3,7 +3,7 @@ title: "Global configuration" linktitle: "Global configuration" description: "Configuring Chainguard Libraries for Java in your organization" type: "article" -date: 2026-06-24T08:04:00+00:00 +date: 2025-03-25T08:04:00+00:00 lastmod: 2026-06-24T14:42:00+00:00 draft: false tags: ["Chainguard Libraries", "Java"] @@ -54,19 +54,18 @@ information. ### Manually managing fallback Chainguard recommends using the Chainguard Repository's built-in [upstream -fallback](/chainguard/libraries/overview/#upstream-fallback-and-controls) -rather than configuring a public registry fallback in your repo manager. -Configuring your own fallback bypasses the protection that the Chainguard -Repository provides. - -However, if upstream fallback is not enabled or you prefer to manage your own fallback -ordering, you can configure `https://libraries.cgr.dev/java/` as a remote -repository alongside your Maven upstream, and combine them in a virtual or group -repository with Chainguard as the first priority. The per-tool instructions on -this page follow this pattern. - -Before configuring your own fallback, consider how you want to handle packages that aren't yet built by Chainguard. If you configure a fallback to Maven Central, packages sourced from that registry are not covered by Chainguard's -malware-resistance guarantees. See the [fallback approaches](/chainguard/libraries/quickstart/#artifact-manager-recommended) described in the Chainguard Libraries quick start for guidance on choosing the right approach for your environment. +fallback](/chainguard/libraries/overview/#upstream-fallback-and-controls) rather +than configuring a public registry fallback in your repo manager. Configuring +your own fallback bypasses the protection that the Chainguard Repository +provides. + +However, if you intentionally want to manage fallback ordering yourself, you can +configure `https://libraries.cgr.dev/java/` as a remote repository alongside +your Maven upstream, and combine them in a virtual or group repository with +Chainguard as the first priority. The per-tool instructions on this page follow +this pattern. If you configure a fallback to Maven Central, packages sourced +from that registry are not covered by Chainguard's malware-resistance +guarantees.