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.
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.
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.
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.
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/
.
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:
In the Application module, navigate to Artifactory | Artifacts.
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.
To set your credentials for API calls such as
publish
andyank
, add the following section to the credentials file under your Cargo home directory (for example~/.cargo/credentials
):[registries.artifactory] token = "Bearer <TOKEN>"
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
In the Application module, navigate to Artifactory | Artifacts.
In the Artifact Tree Browser, select a Cargo repository and click Set Me Up.
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.
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
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.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
When configuring as a Smart Remote repository, the URL should be http://domain/artifactory/cargo-local
While the registry URL should be http://domain/artifactory/api/cargo/cargo-local/index
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:
Edit the configuration file under your Cargo home directory (for example
~/.cargo/config.toml
). In this example we useartprod.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
To set your credentials for API calls such as
publish
andyank
, 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 theData
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.
To reindex a Cargo repository through the REST API, refer to Calculate Cargo Repository Metadata.
Integration Benefits Cargo Registry