Cargo is the official build tool and package manager for the Rust programming language, used to manage project dependencies called crates. Cargo automates the process of downloading dependencies, compiling packages, running tests, and creating distributable packages. Use Cargo repositories in Artifactory to simplify your Rust development workflow with centralized crate management and seamless integration with the Cargo client. You can also use Artifactory as a secure proxy and cache of the public Cargo registry. For more information, see the Cargo documentation.

Artifactory supports the following capabilities for Cargo repositories:

Robust Metadata Capabilities: Calculate metadata for crates hosted in Artifactory's local repositories.
Unified Repository Management: Consolidate all your Cargo repositories in Artifactory as a single source of truth. Set up secure local repositories, access cached versions of remote registries like crates.io.
Support for Cargo CLI: Natively use the Cargo client to deploy, remove, and manage packages in Artifactory.
Fine-Grained Access Control: Manage user and group permissions for your Cargo repositories, giving access based on projects or development teams.

Get Started with Cargo

To get started working with Cargo, complete the following main steps:

Create a Cargo Repository
Connect Cargo to Artifactory
Publish and install crates

Create a Cargo Repository

This topic describes how to create a Cargo repository. This is required before publishing and installing Cargo packages. Artifactory supports two kinds of Cargo repositories:

Local repositories: Store and share first- and second-party packages with your organization
Remote repositories: Download packages from remote locations including external package registries or other Artifactory instances

For more information on JFrog repositories, see Repository Management.

Prerequisites:

You need Admin or Project Admin permissions in Artifactory to create a repository.
Your Artifactory instance must have a custom base URL configured. For more information, see General Settings.

To create a Cargo repository:

In the Administration tab, click Repositories | Create a Repository.
Select the type of repository you want to create: local or remote.
Select the Cargo package type.
Configure the required fields for the repository:
- In the Repository Key field, type a meaningful name for the repository. For example, cargo-local. For more information on local repositories and their settings, see Local Repositories.
- For remote repositories, verify the Registry URL and update as needed. For more information on remote repositories and their settings, see Remote Repositories.

📘
Registry URLs for Remote Repositories
For external repositories, the Registry URL should match the repository URL. For example, https://index.crates.io.
For Smart remote repositories, the URL should be the same as the repository URL, for example: https://company.jfrog.io/artifactory/cargo-repo, while the registry URL should point to the index path, for example: https://company.jfrog.io/artifactory/api/cargo/cargo-repo/index/.

Click Create Repository. The repository is created and the Repositories window is displayed.

Connect Cargo to Artifactory

Prerequisites: Before connecting your Cargo client to Artifactory, you must have an existing Cargo repository in Artifactory. For more information, see Create a Cargo Repository.

Logged in vs. Anonymous User: You can work with Cargo and Artifactory as a logged-in user or anonymously. To work with Artifactory using Anonymous Access, configure that access under Admin > Security > General. For details, refer to Allow Anonymous Access.

📘
Note
Older versions of the Cargo client without sparse index protocol do not authenticate install and search commands. To solve this, turn on the Anonymous download and search setting for the repository. This setting may be required for Cargo version 1.67 and earlier.

To connect the Cargo client to Artifactory:

Open your Cargo configuration file in a text editor. The file is located in the Cargo home directory, for example ~/.cargo/config.toml.

Add the following snippet to point your Cargo client to Artifactory:

[registry]
default = "artifactory"

[registries.artifactory]
index = "sparse+https://[JFrogPlatformURL]/artifactory/api/cargo/<REPO_NAME>/index/"

Where:

[JFrogPlatformURL]: Your organization's Artifactory URL
<REPO_NAME>: The name of your Cargo repository

For example:

[registry]
default = "artifactory"

[registries.artifactory]
index = "sparse+https://company.jfrog.io/artifactory/api/cargo/cargo-local/index/"

Save the changes to the configuration file.
Open your Cargo credentials file in a text editor. The file is located in the Cargo home directory, for example ~/.cargo/credentials.toml.
Add the following snippet to set credentials for API calls like yank and publish:
```
[registries.artifactory]
token = "<AUTH>"
```
Where <AUTH> is your Artifactory identity token. For example:
```
[registries.artifactory]
token = "x7rT4hL9bA2vW1pZ5sE8dR6gK3jCqV0nU7fM9yB4iO1uF2oP5tS8eG7wZ"
```
Save the changed to the credentials file.

📘
Note
You can also use JFrog Set me up to copy the snippet populated with your token and environment. For more information, see Use Artifactory Set Me Up for Configuring Package Manager Clients.

Next steps:

Publish Crates
Install Crates

Publish Crates

Once your Cargo client is connected to Artifactory, you can publish crates natively using the Cargo command line. You can also publish crates using the Artifactory web UI or using the Artifactory API.

To publish a crate:

Run this command:

cargo publish --registry artifactory

✅
Tip
You can override the configured credentials by adding the --token flag in the format --token "<AUTH>", where <AUTH> is your Artifactory identity token or Base64-encoded username:password.
For example:
cargo publish --registry artifactory --token "x7rT4hL9bA2vW1pZ5sE8dR6gK3jCqV0nU7fM9yB4iO1uF2oP5tS8eG7wZ"

Publish Crates via API

You can use the Artifactory API to publish crates directly with a cURL command.

To publish a crate using cURL:

Run the following command:

 curl -u<USERNAME>:<AUTH> -XPUT "https://[JFrogPlatformURL]/artifactory/<REPO_NAME>/crates/<TARGET_PATH>" -T <LOCAL_FILE>

Where:

<USERNAME>: Your Artifactory username
[JFrogPlatformURL]: Your organization's Artifactory URL
<REPO_NAME>: The name of your Cargo repository in Artifactory
<TARGET_PATH>: The target path for publishing the crate in your Cargo repository. For more information, see Cargo Path Format
<LOCAL_FILE>: The path to the crate file on your local machine

For example:

curl -u jeffry:x7rT4hL9bA2vW1pZ5sE8dR6gK3jCqV0nU7fM9yB4iO1uF2oP5tS8eG7wZ -XPUT "https://company.jfrog.io/artifactory/cargo-local/crates/package/package-1.0.0.crate" -T package-1.0.0.crate

Cargo Path Format

When deploying crates directly, make sure the target path is a valid Cargo path format:

crates/<PACKAGE_NAME>/<PACKAGE_NAME>-<VERSION>.crate

If the path deviates from this structure, Artifactory does not identify the package as a Cargo crate and the package will not be indexed. Additionally, make sure your Cargo configuration files contain relevant dependencies and registry URLs.

To avoid indexing errors and other issues, the recommended publishing method is to use the Cargo command line. For more information, see Publish Crates.

Install Crates

Run this command:

cargo install <PACKAGE>

Where <PACKAGE> is the name of the crate you want to install. For example:

cargo install ripgrep

✅
Tip
To resolve multiple registries, add the optional flag --registry <REGISTRY_ID>.

Additional Cargo Information

The following pages provide additional information about using Cargo with Artifactory:

Cargo and Rust Made Easy
Cargo Package Federation Limitation and Workaround
Community Assistance To Support Cargo Virtual Repositories
Index Cargo Repositories
Yank Cargo Crates

Cargo Package Federation Limitation and Workaround

Limitation

Unlike other package managers, Cargo packages contain the URL of the registry where they have been uploaded to. The Cargo client does not support a global URL replacement method, so the client can't modify dynamic URLs. Artifactory cannot change the URLs in each Cargo package because this would change the package checksum and the package would be considered compromised by the client.

This limitation makes it difficult for Artifactory to enable Virtual repositories and Federation unless the following workaround solution is performed.

Cargo Rewrite Workaround Solution

Cargo recommends using Source Replacement on each developer machine to cope with the URL validation from different sources.

For each instance in the federation, configure .cargo/config.toml to identify all the other federation members. Use the replace-with option for each federation source with the target URL. To use FED1, add a source for FED2, and use FED2 replace-with FED1. In this case, all the crates that have FED2 dependencies will be resolved from FED1 as expected.

For information about source replacement, JFrog strongly recommends reading the official Cargo documentation.

Cargo Rewrite Code Example

[registry]
default = "artifactory-local"
global-credential-providers = ["cargo:token"][registries.artifactory-local]
index = "sparse+http://my-awesome.jfrog.io/artifactory/api/cargo/cargo-local/index/"

[source.artifactory-fed1]
registry = "sparse+http://my-awesome.jfrog.io/artifactory/api/cargo/cargo-fed1/index/"replace-with = "artifactory-fed2"

[source.artifactory-fed2]
registry = "sparse+http://my-awesome.jfrog.io/artifactory/api/cargo/cargo-fed2/index/"replace-with = "artifactory-fed1"

#artifactory-remote points to the github registry
[source.artifactory-remote]
registry = "sparse+http://my-awesome.jfrog.io/artifactory/api/cargo/cargo-remote/index/"

[source.crates-io]
replace-with = "artifactory-remote"

Community Assistance To Support Cargo Virtual Repositories

Currently, JFrog Artifactory cannot support Cargo Virtual Repositories due to a Cargo Client limitation that does not provide a method to override dependencies for all Cargo Artifactory users.

What is the problem?

Cargo packages have a configuration file embedded into the package which lists the package's dependencies. Each dependency contains a URL field that is supposed to point to the same location of the package but more than often the URLs point to a source in a different location than the package itself.

Specifically in the Jfrog Artifactory context the ability to modify the source URLs in a scalable manner is crucial for us to provide the Virtual Repository capability since it each dependency can point once to a Local repository and another to a Remote repository.

With this being said, Cargo have provided developers with a solution to override dependencies as documented in Overriding Dependencies - The Cargo Book . Still, unfortunately, it is mostly for development use cases where a single user would set up their specific environment to point to local resources, and it does not provide a scalable method to override dependencies for all users consuming Cargo packages from Artifactory.

For further details please see the full discussions here:

How can you help?

If you are a Cargo developer waiting for virtual repository support in Jfrog Artifactory, we would extremely appreciate your assistance in steering and providing a scalable solution.

Please reach out to us via email here: [email protected]

Index Cargo Repositories

There are several ways to index Cargo repositories:

Using Sparse Indexing
Using Git Indexing
Reindex Cargo Repositories

Index Cargo Repositories 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 use the following syntax: https://[JFrogPlatformURL]/artifactory/<REPO_NAME>/
While the registry URL should use this syntax: https://[JFrogPlatformURL]/artifactory/api/cargo/<REPO_NAME>/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.

Index Cargo Repositories 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):

# Makes artifactory the default registry and saves passing --registry parameter
[registry]
default = "artifactory"
 
 
[registries.artifactory]
index = "https://company.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 and yank, add the following section to the credentials file under your Cargo home directory (for example ~/.cargo/credentials.toml):
```
[registries.artifactory]
token = "<identity_token>"
```

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-index 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

Yank Cargo Crates

Artifactory supports yanking crates in local repositories. Yank a crate to remove the version of the crate from the registry's index and make it unavailable for new dependencies, without removing the code or breaking existing projects that use the crate.

📘
Note
To synchronize yanking in Smart remote repositories and replications, the properties must be synced.

To yank a Cargo crate:

Run the following command:

cargo yank <CRATE> --vers <VERSION> --token "<AUTH>"

Where:

<CRATE>: The name of the crate
<VERSION>: The version of the crate you want to yank
<AUTH>: Your Artifactory identity token

For example:

cargo yank hello_world --vers 0.1.4 --token "7gK9pS4wR2tYqLzV8xN1bM5hC3jF6dEaGuIvPzXoAsDfHjKlQwErTyU0i"

✅
Tip
You can add the --undo flag at the end of the command to un-yank the crate. For example:
cargo yank hello_world --vers 0.1.4 --token "7gK9pS4wR2tYqLzV8xN1bM5hC3jF6dEaGuIvPzXoAsDfHjKlQwErTyU0i" --undo

Cargo Limitations in Artifactory

The following are the limitations of Cargo in Artifactory:

Repository Layout: You need to maintain a path structure to manage crates in local Cargo repositories. Cargo Source packages are uploaded by default using the relative path: crates/<PACKAGE_NAME>/<PACKAGE_NAME>-<VERSION>.crate.
Version Support:
- Artifactory supports Cargo version 1.49.0 and above.
- Artifactory's sparse index requires Cargo version 1.60 or later. For Cargo versions 1.60 through 1.67, you must add the -Z sparse-registry flag to your commands. For versions prior to 1.60, use a Git implementation.
Git Indexing Limitations: Artifactory supports Sparse indexing for Cargo from Artifactory 7.46.3 and by default from 7.58.0. If you use Git indexing, you might experience the following issues and limitations:
- Stability issues with repository initialization
- Non-support of proxy in remote repositories
- Slower performance and build time
Sparse indexing is strongly recommended. For more information, see Index Cargo Repositories Using Sparse Indexing
Authentication with Older Versions of Cargo: If your Cargo repository requires authentication and you are using Cargo version 1.67 or earlier, you may need to enable the Allow anonymous download and search setting in order for install and search commands to work. This is because older versions of the Cargo client without sparse indexing do not send authentication headers with install and search commands.
Federation Limitations and Workaround: Due to the hardcoded registry URLs in crate files, which cannot be modified without invalidating the package checksum, Federation and virtual repositories are not supported for Cargo in Artifactory. However, there is a workaround for Federation. For more information, see Cargo Package Federation Limitation and Workaround.