Cargo Package Registry

JFrog Artifactory Documentation
ft:sourceType
Paligo

Overview

From JFrog Artifactory 7.17.4, the Cargo registry is supported for the Rust programming language, giving you full control of your deployment and resolving Cargo packages. Cargo downloads your Rust package's dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io, the Rust community’s package registry. You can contribute to this book on GitHub.

Note

We support Cargo Sparse indexing from Artifactory 7.46.3 and by default from 7.58.0. If you still use Git indexing, you might experience the following issues and limitations:

  • Repository initialization might experience stability issues.

  • The Git implementation does not support proxy in remote repositories.

  • Performance and build time might be slightly slower.

Therefore, we strongly recommend updating to Sparse indexing. For more information, see Cargo Indexing Using Sparse Indexing.

About Rust Programming Language

Rust is a programming language designed for performance and safety, with an emphasis on safety concurrency. A crate is a compilation unit in Rust. Using Cargo, you can publish libraries on crates.io, organize large projects with a workspace, install binaries from crates.io and extend Cargo using custom commands.

Learn More

Cheatsheet for managing applications using Rust & Cargo

Cargo repositories in Artifactory offer the following benefits:

  • Secure and private local Cargo repositories with fine-grained access control

  • The ability to proxy remote Cargo resources and cache downloaded Cargo packages to keep you independent of the network and the remote resource

  • Metadata calculation of the Cargo packages hosted in the Artifactory local repositories

  • Version management: Archiving older versions of the packages uploaded to local repositories

  • Source and binaries management

Supported Cargo Version

Artifactory supports Cargo version 1.49.0 and above.

Configuration

Local Repositories

To enable the calculation of Cargo metadata, in the Administration module, go to Repositories| Repositories | Local and select Cargo as the Package Type when you create your local repository.

cargo repository icon.png

Prerequisite

Prior to setting a local repository, you will need to configure a Custom Base URL for the Artifactory instance. For more information, see General Settings.General Settings

Local Repository Layout

You will need to maintain a specific path structure to manage the Cargo packages that are uploaded to Cargo local repositories.

Cargo Source packages are automatically uploaded by default to the relative path: crates/{package_name}/{package_name}-{version}.crate.

Yank and Un-yank Crates in Local Repositories

Artifactory supports yanking and un-yanking crates in local repositories.

Cargo Yank/ Un-yank

cargo yank hello_world --vers 0.1.4 --token "Bearer (token)"
cargo yank hello_world --vers 0.1.4 --token "Bearer (token)" --undo

Yank/ Un-yank Smart Repositories

To synchronize yanking in Smart remote repositories/replications, the properties must be synced.

Remote Repositories

Prerequisite

Prior to setting a remote repository, you will need to configure a Custom Base URL for the Artifactory instance that is required to support. For more information, see General Settings.General System Settings

You can create remote Cargo repositories to proxy and cache remote repositories or other Artifactory instances.

The Registry URL has been added to Cargo remote repositories, to reflect the index (git) location:

  • For external repositories, the registry URL should be the same as the repository URL. For example: https://github.com/rust-lang/crates.io-index.

  • For Smart remote repositories, the URL should be the same as the repository URL, for example: https://RTURL/artifactory/$repo, while the registry URL should point to the index path, for example: https://RTURL/artifactory/api/cargo/cargoh/index/.

Cargo_sparse_smart.png
Virtual Repositories Not Supported

Currently, virtual repositories are not supported for Cargo Package Registry, as the Cargo client is not able to add or change sources in the .cargo/config.toml file. Developers in the Cargo community are invited to collaborate with us to find a solution for this issue as discussed in the Rust forum and in GitHub via this ticket: RTFACT-29890.

Resolving Cargo Packages

To resolve Cargo packages:

  1. In the Application module, navigate to Artifactory | Artifacts.

  2. In the Artifact Tree Browser, select a Cargo repository and click Set Me Up.

    Password Authentication Requirement

    The 'Type Password' box is displayed only if you need to perform re-authentication opposite the JFrog Platform. This option will not be available in the UI for users applying external authentication methods such as SAML or OAuth.

    Cargo_sparse_SMU.png

    To set your credentials for API calls such as publish and yank, add the following section to the credentials file under your Cargo home directory (for example ~/.cargo/credentials):

    [registries.artifactory]
token = "Bearer <TOKEN>"

  3. Copy the Cargo code snippets to publish a Cargo package or configure your Rust client to resolve the artifacts in the selected repository.

Resolving Cargo Packages Using the Rust Command Line

  1. In the Application module, navigate to Artifactory | Artifacts.

  2. In the Artifact Tree Browser, select a Cargo repository and click Set Me Up.

  3. Install a package using the Cargo build or install commands.

    Cargo install

    cargo install crate

    Resolving Multiple Cargo Registries

    To resolve multiple registries, add this optional flag --registry (registryId).

Authentication: Allow Anonymous Downloads

The Cargo client does not send any authentication header when running install and search commands.

Select "Allow anonymous download and search" to block anonymous requests but still allow anonymous Cargo client downloads and performing search, to grant anonymous access specifically to those endpoints for the specific repository.

Cargo_sparse_smart.png

Deploying Cargo Packages

You can deploy packages to a local Cargo repository using the Cargo Client, using the Deploy feature in the UI, or using a cURL request.

Deploying a Package Using the Cargo Client (Recommended)

To deploy a package, run the following Cargo publish command.

Cargo install

cargo publish or cargo publish --registry (registry id)

To override the credentials for that repository, run the following command.

Cargo install

cargo publish --token "Basic (base64 of user:password)"or cargo publish --token "Bearer (access token)"
Deploying a Package Using the UI

You can either drag and drop, or select a Cargo package to upload in Deploy in the UI. Artifactory will automatically identify if the package is a source or binary package.

Target Path

It is important to be aligned with the following layout to support this feature.

crates/{package_name}/{package_name}-{version}.crate
deploy_cargo.png
Deploying a Package Using cURL

To deploy a package using a cURL request.

Deploying Cargo Crates

curl -uadmin:password -XPUT "http://localhost:8082/artifactory/cargo-local/crates/package_1.0.0.crate" -T package_1.0.0.crate

When deploying directly (PUT request to a specific path), make sure the target path is a valid Cargo path.

crates/{package_name}/{package_name}-{version}.crate

Note that deploying a package to a different path will not identify the package as Cargo package, and will not invoke metadata indexing.

Viewing Individual Cargo Package Information

Artifactory lets you view selected metadata of a Cargo package directly from the UI.

In the Artifact Repository Browser, select your local Cargo repository and scroll down to find and select the package you want to inspect.

The metadata is displayed in the Cargo Info tab, or view in the Packages view.

Cargo Indexing

Cargo Indexing Using Sparse Indexing

From Artifactory version 7.46.3, Cargo sparse indexing is supported. Sparse Indexing allows you to control the connections that are entered into the index database. Sparse indexing also allows for:

  • Faster build times, since no Git clones/ pulls are involved

  • Using a proxy for Remote Cargo Repositories.

Note

Cargo sparse indexing is supported from Cargo version 1.68 and higher (from Cargo 1.60 it is supported as a nightly feature).

To enable Cargo sparse indexing:

  • Via REST API: Add the "cargoInternalIndex": true flag to the Repository Configuration JSON file.Repository Configuration JSON

  • Via the JFrog Platform UI: Select the Enable sparse index support checkbox in the General Settings section of the Cargo Repository Basic tab.

For existing repositories, reindex after enabling sparse indexing. For new repositories, no initialization time is required, as no Git clone is created behind the scenes.

Rules and Guidelines

To use the official Rust Remote Repository URL, create a remote repository with the URL and registry URL https://index.crates.io.

For more information, see the Rust documentation.

Cargo Indexing Using Git Indexing

Note

From Artifactory version 7.58.x, the default method for Cargo indexing is sparse indexing. However, If you are using an Artifactory earlier than 7.46.3, or a Cargo client earlier than 1.60, you may need to use Cargo Git Indexing.

To configure the Cargo client to work opposite JFrog Artifactory using Git indexing:

  1. Edit the configuration file under your Cargo home directory (for example ~/.cargo/config.toml). In this example we use artprod.mycompany to represent the Artifactory:

    # Makes artifactory the default registry and saves passing --registry parameter
[registry]
default = "artifactory"
 
 
[registries.artifactory]
index = "https://productdemo.jfrog.io/artifactory/git/bank32-cargo-local-2.git"
 
# For sending credentials in git requests.
# Not required if anonymous access is enabled
[net]
git-fetch-with-cli = true

  2. To set your credentials for API calls such as publish and yank, add the following section to the credentials file under your Cargo home directory (for example ~/.cargo/credentials.toml):

    [registries.artifactory]
token = "Bearer pm-admin:<PASSWORD> (converted to base 64)"
Git Support for Cargo Repositories

As the Cargo Client requires the Cargo registry to be a Git repository, the following Git support has been applied in Artifactory:

  • An internal .git folder exists for each Cargo repository to reflect the index .git files. This folder is recreated after every reindexing process.

  • An internal git directory in the Data directory of Artifactory has been added for each Cargo repository. This is a local clone that will be recreated following each restart or repository init.

Re-indexing a Cargo Repository

You can trigger an asynchronous re-indexing of a local Cargo repository either through the UI or using the REST API.

This will also reindex the git index and, as a result, will also index the remote repositories.

In the Artifact Tree Browser, select your Cargo repository, right-click and select Recalculate Index from the list. Requires Admin privileges.

cargo_local_reindexing.png

To reindex a Cargo repository through the REST API, refer to Calculate Cargo Repository Metadata.Calculate Cargo Repository Metadata

Integration Benefits Cargo Registry