User Guide

Using chartered as a user is actually pretty simple, it's very much like your standard Cargo registry except with two extra concepts: organisations and permissions.

Organisations are very much like the organisations you'll likely have used on your preferred SCM host, a group of users that have group-level permissions, in Chartered case the permissions these users may have are:

Permissions

  • VISIBLE
    • Essentially the base-level permission meaning the user belongs to the group, if the user doesn't have this permission they're not in the group, this permission at the crate-level means the user can download the crate and see it in the WebUI.
  • PUBLISH_VERSION
    • Gives the ability to publish a new version for crates belonging to the group.
  • YANK_VERSION
    • Gives the ability to yank (and unyank) published versions for crates belonging to the group.
  • MANAGE_USERS
    • Gives the ability to add (and remove) users from the group, and crates belonging to the organisation.
  • CREATE_CRATE
    • Gives the ability to create a new crate under the organisation.

All these permissions, with the exception of CREATE_CRATE, can also be used at the crate-level for giving extra permissions to org members for a particular crate - or even users outside of the org. Bare in mind, however, these permissions are additive - it is not possible for permissions to be subtracted from a user at the crate-level if they have been granted them by the organisation.

Publishing your first crate

With all this in mind, it's about time you started publishing your first crate!

Chartered has excellent integration with Cargo's alternative registry implementation and is used very much like a standard alternative registry. The only prerequisites for publishing your crate are:

  1. Have an SSH key added to your Chartered account, which you can do via the WebUI
  2. Belong to an organisation you have the PUBLISH_VERSION permission for, anyone can create a new organisation if you don't already belong to one.

And once you're ready, you can add the organisation's registry to your .cargo/config.toml like so:

[registries]
my-organisation = { index = "ssh://ssh.chart.rs/my-organisation" }

(You should create this file if it doesn't already exist)

You can now publish the crate using cargo as you normally would, except with the registry specified:

$ cargo publish --registry my-organisation --token ""

Note: the token is purposefully empty, as the token will be vended by the index based on your SSH key.

Pulling in dependencies

Again, not too dissimilar from using crates.io, you can declare your dependencies as normal with the exception that you need to specify the organisation the crate should be pulled from provided you've declared the organisation in .cargo/config.toml as shown in the previous section of this guide.

[dependencies]
my-other-crate = { version = "0.1", registry = "my-organisation" }

Your other Cargo dependencies from crates.io can be declared as normal alongside organisation dependencies.