Global Configuration

JavaScript and npm package consumption in a large organization is typically managed by a repository manager. Commonly used repository manager applications are JFrog Artifactory, Sonatype Nexus Repository, and others. 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 the Chainguard Libraries for JavaScript registry as a remote repository for library retrieval.
• Configure the 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 optional measures:

• Remove all cached libraries in the proxy repository of the npm Registry. 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 tools for more information.

Cloudsmith

Cloudsmith supports npm registries repositories for proxying and hosting. Refer to the npm registry documentation and the npm Upstream documentation for Cloudsmith for more information. Cloudsmith supports combining repositories by defining multiple upstream repositories.

Initial configuration

Use the following steps to add a repository with the npm registry and the Chainguard Libraries for JavaScript repository as npm upstream repositories.

Configure a javascript-all repository:

1. Log in as a user with administrator privileges.
2. Select the Repositories tab near the top of the screen.
3. On the Repositories page, click the + New repository button.
4. Enter the name javascript-all for your new repository. The name should include javascript to identify the ecosystem. This convention helps avoid confusion since repositories in Cloudsmith are multi-format.
5. Select a storage region that is appropriate for your organization and infrastructure.
6. Press + Create Repository.

Configure an upstream proxy for the npm registry:

1. Click the name of the new javascript-all repository on the repositories page to configure it.
2. Access the Upstreams tab and click + Add Upstream Proxy.
3. Configure an upstream proxy with the format npm and the following details:
4. Configure another upstream proxy with the following details
   • Name javascript-public
   • Priority 2
   • Upstream URL https://registry.npmjs.org/
   • Mode Cache and Proxy
5. Press Create Upstream Proxy.

Configure an upstream proxy for the Chainguard Libraries for JavaScript repository:

1. Click the name of the new javascript-chainguard repository on the repositories page to configure it.
2. Access the Upstreams tab and click + Add Upstream Proxy.
3. Configure an upstream proxy with the format npm and the following details:
   • Name javascript-chainguard
   • Priority 1
   • Proxy URL https://libraries.cgr.dev/javascript/
   • Mode Cache and Proxy
   • Add the Username and Password value from Chainguard Libraries access in Authentication Settings
4. Press Create Upstream Proxy.

Use this setup for initial testing with Chainguard Libraries for JavaScript. For production usage, add the javascript-chainguard upstream proxy to your production repository.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Select the Packages tab.
2. Press Push/Pull Packages.
3. Choose the format NPM.
4. Refer to the Pull Package tab.
5. Note the registry URL and syntax from the code snippets for npm. For example, the URL for the registry in the example organization is https://npm.cloudsmith.io/example/javascript-all/.
6. Note that authentication is using an authentication token and the syntax for npm in the example organization is //npm.cloudsmith.io/example/javascript-all/:_authToken=YOUR-API-KEY

Use the provided code snippets directly for your use with npm, or adjust as necessary for other JavaScript build and packaging tools. Find relevant details in the Build Configuration and specific packaging tool documentation.

Use the following steps to retrieve the necessary API key as an authentication token for the registry access:

1. Click on your user name at the top, right corner.
2. Select Personal API keys*.
3. Authenticate again in the Confirm access dialog.
4. Create a new token or refresh the existing one in case you lost the token value.

JFrog Artifactory

JFrog Artifactory supports npm repositories for proxying and hosting, and virtual repositories to combine them. Refer to the npm registry documentation for Artifactory for more information.

Initial configuration

Use the following steps to add the npm Registry and the Chainguard Libraries for JavaScript repository as remote repositories and combine them as a virtual repository:

1. Log in as a user with administrator privileges.
2. Press Administration in the top navigation bar.
3. Select Repositories in the left hand navigation.

Configure a remote repository for the npm Registry:

1. Press Create a Repository and choose the Remote option.
2. Select Npm as the Package type.
3. Set the Repository Key to javascript-public.
4. Set the URL to https://registry.npmjs.org .
5. Press Create Remote Repository.

Configure a remote repository for the Chainguard Libraries for JavaScript repository:

1. Press Create a Repository and choose the Remote option.
2. Select Npm as the Package type.
3. Set the Repository Key to javascript-chainguard.
4. Set the URL to https://libraries.cgr.dev/javascript/.
5. Set User Name and Password / Access Token to the values as retrieved with chainctl.
6. Press Create Remote Repository.

Combine the two repositories in a new virtual repository:

1. Press Create a Repository and choose the Virtual option.
2. Select Npm as the Package type.
3. Set the Repository Key to javascript-all.
4. Scroll down to the Repositories section.
5. Add the javascript-chainguard and javascript-public repositories. Ensure the javascript-chainguard repository is the first in the displayed list. Use the icon on the right of the repository name to drag and drop repositories into the desired position.
6. Press Create Virtual Repository.

Use this setup for initial testing with Chainguard Libraries for JavaScript. For production usage add the javascript-chainguard repository to your production virtual repository.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Press Administration in the top navigation bar.
2. Select Repositories in the left hand navigation.
3. Select the Virtual tab in the repositories view.
4. Locate the javascript-all repository.
5. Hover over the row and click the … in the last column on the right.
6. Select Set Me Up in the dialog.
7. Press Generate Token & Create Instructions.
8. Copy the generated token value to use as the password for authentication.
9. Press Generate Settings.
10. Copy the value from a url field. The are all identical. For example, https://exampleorg.jfrog.io/artifactory/javascript-all/ with exampleorg replaced with the name of your organization.

Use the URL of the virtual repository in the build configuration and build a first test project. In a working setup the chainguard remote repository contains all libraries retrieved from Chainguard.

Sonatype Nexus Repository

Sonatype Nexus Repository allows for merging multiple remote repositories as a repository group. The below instructions for are based on the Nexus documentation for npm.

Initial configuration

For initial testing and adoption it is advised to create a separate proxy repository for the npm registry, a separate proxy repository Chainguard Libraries for JavaScript repository, and a separate repository group:

1. Log in as a user with administrator privileges.
2. Access the Server administration and configuration section with the gear icon in the top navigation bar.

Configure a remote repository for the npm Registry:

1. Select Repository - Repositories in the left hand navigation.
2. Press Create repository.
3. Select the npm (proxy) recipe.
4. Provide a new name javascript-public.
5. In the Proxy - Remote storage input add the URL https://registry.npmjs.org/.
6. Press Create repository.

Configure a remote repository for the Chainguard Libraries for JavaScript repository:

1. Select Repository - Repositories in the left hand navigation.
2. Press Create repository.
3. Select the npm (proxy) recipe.
4. Provide a new name javascript-chainguard.
5. In the Proxy - Remote storage input add the URL https://libraries.cgr.dev/javascript/.
6. In HTTP - Authentication with the Authentication type Username, provide the username and password values as retrieved with chainctl.
7. Press Create repository.

Combine a new repository group and add the two repositories:

1. Select Repository - Repositories in the left hand navigation.
2. Press Create repository.
3. Select the npm (group) recipe.
4. Provide a new name javascript-all.
5. In the section Group - Member repositories, move the new repositories javascript-public and javascript-chainguard to the right and move the javascript-chainguard repository to the top of the list with the arrow control.

Build tool access

The following steps allow you to determine the URL and authentication details for accessing the repository:

1. Click Browse in the Welcome view or the browse icon (cube) in the top navigation bar.
2. Locate the URL column for the javascript-all repository group and press copy. For example, https://repo.example.com/repository/javascript-all/ with repo.example.com replaced with the hostname of you repository manager.
3. Copy the URL in the dialog.
4. Use your configured username and password unless Security - Anonymous Access - Access - Allow anonymous users to access the server is activated. Details vary based on your configured authentication system.

Use the URL of the repository group, such as https://repo.example.com/repository/javascript-all/ in the build configuration and build a first test project. In a working setup the javascript-chainguard proxy repository contains all libraries retrieved from Chainguard.