Home

Awesome

<div align="center"> <h1>📦 Cratery</h1> <strong>Lightweight private cargo registry with batteries included, built for organisations</strong> </a> <br> <br>

Build Status Cratery Crates.io version Cratery Rust documentation Cratery dependency status docker

</div>

Quickstart

To launch an empty registry using a pre-built docker image, get the latest docker-compose.yml file and start it:

git clone https://github.com/cenotelie/cratery
cd cratery
docker compose up -d

Then, connect to http://localhost/. In the default configuration, a Google account must be used.

The first ever user to log in automatically obtains administration rights. He/she is then responsible to setup an admin team.

Once connected, a token for CLI usage in Cargo can be obtained by going to http://localhost/webapp/account.html and clicking on the Create new token button. Tokens can be restricted to read access, e.g. for CI purposes. For publishing crates, a token with write accesses must be obtained. The name of the token is just a convenience. On creation, a popup appear with information about how to register this token for Cargo.

Features

Authentication

Authentication is handled using OAuth out of the box. Simply connect your organisation's provider. On the default configuration, Google is configured as a provider. This is only appropriate for demonstration purposes.

Administration

Administrate owners for hosted crates.

Screenshot of the admin panel for setting a crate's owner

Docs generation

Cratery automatically generates and serves the documentation for published crates.

Screenshot of a piece of documentation

Cratery now supports worker nodes for the execution of documentation generation jobs, as well as the configuration of crates so that the documentation can be generated:

Screenshot of the settings page for a crate for documentation generation

Dependency analysis

Cratery automatically scans the dependency graph of the latest versions (for each major version) of hosted crates. Cratery detects outdated direct dependencies and gives the latest version number to use instead. Cratery also audits the complete dependency graph to find dependencies, direct or indirect, that are affected by vulnerabilities published by the RustSec group.

Cratery can send notifications by emails to the crates' owners when a issue is discovered. Analysis are also performed on-demand on each crate's page.

Screenshot of warning about outdated dependencies

Screenshot of warning about vulnerable dependencies

Statistics

Cratery also tracks downloads to give you statistics about the usage of your crates.

Screenshot of download statistics for a crate

Configuration

Configuration is passed through environment variables. See docker-compose.yml for all values.

General

Authentication

Authentication on cratery is archived with OAuth and configured with the REGISTRY_OAUTH_* environment variables. The docker-compose.yml file contains the basic configuration to use Google as the authentication provider. This is allowed only for cratery instances exposed on localhost for evaluation and testing purposes. This configuration must be changed to use your own OAuth identity provider.

Storage

The persisted data for cratery is:

By default, all data is stored in a single directory specified by the REGISTRY_DATA_DIR environment variable. The default value is a /data folder, expected to be mounted into the docker container.

In addition, cratery uses git and Cargo and expect their respective configuration to appear in a home directory. This directory can be configured using the REGISTRY_HOME_DIR environment variable. If this variable is not set, cratery looks for the HOME environment variable and then fallback to a default value of home/cratery expecting to run within a docker container.

The crates data and their generated documentation can be stored on S3 instead. This is controlled by the following configuration :

Index

The index can be served using both the legacy git and the new sparse protocols, see Registry Protocols. The legacy git protocol is disabled by default, and the new sparse protocol enabled:

Fetching the index always requires authentication, regardless of the used protocol.

The index for the registry is managed as a git repository. When cratery commits to this repository as an author:

The git repository for the index can be synchronized with an externally hosted git repository with:

Docs generation

When generating the documentation for stored crates:

cratery will automatically link to docs.rs for dependencies on crates.io. Dependencies to crates also hosted on the same cratery instance will be recognized using the REGISTRY_WEB_PUBLIC_URI value.

External private registries so that documentation can be generated and the dependencies' docs linked against. This is specified with the following environment variables. {index} is a number that starts at 1 for the first external registry.

Dependency analysis

When performing dependency analysis, Cratery will access crates.io and other external registries.

Worker nodes

Documentation jobs do not have to be executed on the server, although this is the default setup. They can be delegated to worker nodes and the main server will act as the master. A worker node is just another instance of cratery, configured with a specific role. The role of a node is configured as follow:

Contributing

Contributions are welcome!

Open a ticket, ask a question or submit a pull request.

License

This project is licensed under the MIT license.