Skip to main content

Rust / Cargo Repositories

Rust is known for its memory safety, concurrency, and performance. Cargo, Rust's build tool and package manager, automates dependency management through building and testing your application.

Cargo uses a Cargo.toml manifest file to declare project dependencies. Cargo uses this manifest to fetch and build these dependencies from the public registry ensuring consistent builds. It automates the compilation and linking process, including handling builds for different target platforms and configurations.

Supported Features and Limitations

This section covers supported features and limitations for Rust Cargo in the Nexus Repository.

  • Supported Repository Types

    Nexus Repository supports Cargo hosted, proxy, and group repositories.

  • Component Upload via Cargo Publish Only

    Nexus Repository does not currently support uploading components via the UI or API; use the cargo publish command to publish components to a hosted repository.

  • Supports the Cargo Sparse Protocol

    Nexus Repository only supports Cargo's sparse protocol; the Git protocol is not supported.

  • Incompatible with Community Plugin

    Nexus Repository's support for Rust Cargo is not compatible with the community plugin. You will not be able to migrate data from the plugin.

  • Cargo Versions - 1.68+

  • Cargo Search

    Nexus Repository does not support the Cargo client native search capability

  • Support for Yank and Unyank

    Nexus Repository does support yank and unyank endpoints; however, use yank with caution as it can break builds for users who haven't locked their dependencies

Proxy Configuration

When setting the proxy repository include a trailing slash ('/') on the Remote URL.

https://index.crates.io/

Example Rust Configuration

Cargo's config.toml is a configuration file used to set up Rust's package manager (Cargo) to work with Nexus Repository. This file is important when configuring Cargo to use Nexus Repository as a proxy or hosted repository for Rust packages.

Use the sparse+ prefix in your registry URL. This is required for the Cargo sparse protocol.

Example config.toml:

[registries]
cargo-proxy = { index = "sparse+http://nexus.example/repository/cargo-proxy/" }
cargo-group = { index = "sparse+http://nexus.example/repository/cargo-group/" }

[registries.cargo-hosted]
index = "sparse+http://nexus.example/repository/cargo-hosted/"
token = "Basic YWRtaW46YWRtaW4xMjM="

[source.crates-io]
replace-with = "cargo-proxy" # Change it dependening of the test case

Key elements in this configuration:

  • [registries]: configures global settings for Cargo registries.

  • [source.crates-io]: configures Cargo to replace the default crates.io source with your Nexus repository

  • [registries.cargo-hosted]: defines the Nexus Repository, with the sparse+ prefix indicating the use of Cargo's Sparse protocol. The user token is included for authentication.

Security Configuration

Use SSL configuration (HTTP/HTTPS settings) for secure data transfer and repository access.

Cargo clients rely on a specific signal in the config.json file to determine authentication requirements, which could lead to unexpected behavior when anonymous access is enabled in Nexus Repository but restricted by the individual Cargo repository.

When creating proxy or group Cargo repositories, use the Restrict repository content to authenticated users checkbox to set auth-required in /config.json responses and ignore anonymous access configuration.

Authenticating with User Tokens for Cargo

For Cargo, user tokens are configured in the Cargo credentials config file (credentials.toml). Each token is associated with a specific repository and only authenticates access to that particular repository. Tokens are primarily used during the crate publishing process.

To use your user token for Cargo repository authentication, take the following steps:

  1. Generate and access your user token following the instructions in our user token help documentation. Copy the base64 representation of your user token.

  2. Open your Cargo credentials config file (credentials.toml); add and save the following lines, replacing the registry name with the name of your repository, and <your-token> with the base64 representation of your user token:

    [registries.cargo-hosted]
token = "Basic <your-token>"

[registries.my-hosted-repo]
token = "Basic <your-token>"

    Alternatively, you can use a command like the following to update the file:

    cargo login --registry <your-repo-name>

    This will result in a prompt for your repository's token. Provide it as Basic <your-token> to update the file.

    Or, you can use an environment variable by running a command like the following:

    export CARGO_REGISTRIES_<REPO_NAME>_TOKEN="Basic <your-token>"

  3. You can test your authentication by running a command like cargo publish to publish a crate to your hosted repository.