Global Configuration

Configuring Chainguard Libraries for Python in your organization

Python library consumption in a large organization is typically managed by a repository manager. Commonly used repository manager applications are Cloudsmith, JFrog Artifactory, and 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.
  • Add the public PyPI repository as a remote repository.
  • Create a group, virtual, or polyglot repository combining these repository sources with any desired internal repositories. Configure the Chainguard Libraries repository as the first choice for any library access after any desired internal repositories.

You should also:

  • Remove all prior cached artifacts in the virtual server or proxy public repository. This step reduces confusion about the origin of libraries and assists technical evaluation and adoption of Chainguard Libraries.
  • 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.

If your organization does not use a repository manager, you can still use Chainguard Libraries. However, this approach requires configuration of multiple build and development platforms and utilities to use Chainguard Libraries. For this reason, adopting the use of a repository manager is the recommended approach.

Cloudsmith

Cloudsmith supports Python repositories for proxying and hosting and polyglot repositories that combine multiple repositories sources with compatible formats. Refer to the Cloudsmith Python Repository documentation and the Cloudsmith documentation for creating a repository for more information.

Initial configuration

Use the following steps to add a polyglot repository with both Chainguard Libraries and PyPI as upstream sources.

First, create a repository:

  1. Log in to your Cloudsmith instance as a user with administrator privileges.
  2. Select the Repositories tab near the top of the screen.
  3. Navigate to the Repositories Overview, then select + New repository.
  4. At the new repository form, enter the name chainguard-python for your new repository. The name should include python to identify the repository format. 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. Select + Create Repository.

Next, configure an upstream proxy for the PyPI Repository:

  1. Select the name of the new chainguard-python 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 python and the following details:
    • Name: chainguard-libraries
    • Priority: 1
    • Upstream URL: https://libraries.cgr.dev/python/
    • Mode: Cache and Proxy
  4. Configure another upstream proxy with the following details
    • Name: pypi
    • Priority: 2
    • Upstream URL: https://pypi.org/
    • Mode: Cache and Proxy
  5. Select Create Upstream Proxy.

Build tool access

See the page on build tool configuration for Chainguard Libraries for Python for information on accessing credentials and setting up build tools.

JFrog Artifactory

JFrog Artifactory supports PyPI repositories for proxying and virtual repositories to combine multiple sources into a single repository. The following instructions are based on on the PyPI Repository documentation for Artifactory.

Initial configuration

Use the following steps to add the Chainguard Libraries for Python index and the PyPI public index as remote repositories and combine them as a virtual repository:

First, configure a remote repository for the Chainguard Libraries for Python index:

  1. Log in to your Artifactory instance as a user with administrator privileges.
  2. Select Create a Repository and choose the Remote option.
  3. Select PyPI as the Package type.
  4. Set the Repository Key to chainguard.
  5. Set the URL to https://libraries.cgr.dev/python/.
  6. Set User Name and Password / Access Token to the values as retrieved with chainctl.
  7. Check the Enable Token Authentication checkbox.
  8. Select Test to validate the connection.
  9. Press Create Remote Repository.

Configure a remote repositry for the PyPI public index:

  1. Select Administration in the top navigation bar.
  2. Select Repositories in the left hand navigation.
  3. Select Create a Repository and choose the Remote option.
  4. Select PyPI as the Package type.
  5. Set the Repository Key to pypi.
  6. Set the URL to https://pypi.org/.
  7. Select Create Remote Repository.

Combine the two repositories in a new virtual repository:

  1. Press Create a Repository and choose the Virtual option.
  2. Set the Repository Key to chainguard-python.
  3. In the Repositories section,, find the chainguard and pypi repositories. Ensure the 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.
  4. Select Create Virtual Repository.

Build tool access

See the page on build tool configuration for Chainguard Libraries for Python for information on accessing credentials and setting up build tools.

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 PyPI

Initial configuration

The following will create remote repositories for Chainguard Libraries for Python, a remote repository for the public PyPI index, and a repository group combining these sources.

First, log in to Sonatype Nexus as a user with administrator privileges and access the Server administration and configuration section within the gear icon in the top navigation bar.

Next, configure a remote repository for the public PyPI index:

  1. Select Repository - Repositories in the left hand navigation.
  2. Select Create repository.
  3. Select the PyPI (proxy) recipe.
  4. Provide a new name, such as pypi-proxy.
  5. In the Proxy - Remote storage field, add the following URL: https://pypi.org/.
  6. Select Create repository.

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

  1. Select Repository - Repositories in the left hand navigation.
  2. Select Create repository.
  3. Select the PyPI (proxy) recipe.
  4. Provide a new name, such as chainguard-proxy.
  5. In the Proxy - Remote storagefield, add the following URL: https://libraries.cgr.dev/python/.
  6. In HTTP - Authentication, set the Authentication type to username and enter the the username and password values as retrieved with chainctl.
  7. Select Create repository.

Finally, create a new repository group and add the two repositories:

  1. Select Repository - Repositories in the left hand navigation.
  2. Select Create repository.
  3. Select the PyPI (group) recipe.
  4. Provide a new name, such as chainguard-python.
  5. In the section Group - Member repositories, move the new repositories pypi-proxy and chainguard-proxy to the right and move the chainguard repository to the top of the list with the arrow control.

Build tool access

See the page on build tool configuration for Chainguard Libraries for Python for information on accessing credentials and setting up build tools.

Last updated: 2025-04-07 14:42