🚚 The Ktra Book

Your Little Cargo Registry.

Sections

About Ktra

To know about Ktra:

Overview

What is `Ktra`?

Ktra is a implementation of the Alternate Registry that is introduced for non-public crates in Rust/Cargo 1.34.

In other words, Ktra is an all-in-one package for the private cargo registry.

If you write a Rust crate in your job, your codes might be proprietary and/or closed-source.
crates.io cannot host closed-source crates so you have to construct a private registry by yourself.
Ktra could help to reduce that annoying operations.

What does `Ktra` mean?

Ktra is named after shortened name of Kei truck which is a japanese style mini pickup truck.

You can pronounce Ktra as you like.
For your information, most native japanese speaker do it KEI-TORA or KE-TORA.

License

Ktra is icensed under either of Apache License, Version 2.0 or MIT license at your option.

Features

Ktra has now features listed below.

Almost pure Rust.
Minimum Alternate Registry implementation.
Secure user management with Argon2.
Sled as its internal database.
- via db-sled feature turned on by default.
Redis support.
- via db-redis feature.
MongoDB support.
- via db-mongo feature.

Installation

To install Ktra:

Cargo
Docker (coming soon)

Install With Cargo

You can install Ktra simply with just running a command below.
This command will install the default Ktra enabled secure-auth and db-sled features.

cargo install ktra

If you want to select the backended database:

db-redis

cargo install ktra --no-default-features features=secure-auth,db-redis

db-mongo

cargo install ktra --no-default-features features=secure-auth,db-mongo

Install With Docker

You can also install Ktra with the Docker image.

docker pull ghcr.io/moriturus/ktra:latest

Or, if you want to pull a fixed version image, try this.

docker pull ghcr.io/moriturus/ktra:0.4.3

Note:
The latest published Ktra version is .

Registry

All of the docker images are built with emk/rust-musl-builder image and stored at GitHub Container Registry.
These are public images so you can pull them without any authentication.

Quick Start

To start Ktra quickly:

Create Index Git Repository

The Index Repository serves data read by cargo command when you build a crate depending on another crate hosted on Ktra.
You can use any git repository hosting service such as GitHub, GitLab and Bitbucket even if its repository is private.
Additionally, of course, you can use private git repository managed by yourself.

This book introduces the simplest way to create the index repository with GitHub.

1. Go to Create new repository page. (login needed)

For more details, please see GitHub official documents.

The index repository's name is arbitrary.
Public or private either is fine.

2. Clone the repository created above.

Note:
You have to create an access token in advance to clone with HTTPS protocol.
Please see the GitHub official documents.

git clone https://github.com/YOUR_USERNAME/YOUR_INDEX.git

3. Create `config.json` file then commit and push it to remote repository.

Note:
Please make sure your branch name.
main is the default on GitHub but GitLab, Bitbucket and other git repository hosting services might default to master instead of main.

cd YOUR_INDEX
echo '{"dl":"http://localhost:8000/dl","api":"http://localhost:8000"}' > config.json
git add config.json
git commit -am "initial commit"
git push origin main

4. Edit your `.cargo/config.toml`.

Note 1:
Please see Cargo official documents for more details.

Note 2:
To make git remember your credential, please use the credential helper.

[registries]
ktra = { index = "https://github.com/YOUR_USERNAME/YOUR_INDEX.git" }

Create Ktra Configuration File

About

Ktra Configuration File is a TOML formatted document file.
To configure Ktra's database, index and crate files, you should write it and pass the path to it as a command argument.

Sample

Note 1:
All configurations are listed on Appendix: Configurations page.

Note 2:
Please make sure your branch name AGAIN.
main is the default on GitHub but GitLab, Bitbucket and other git repository hosting services might default to master instead of main.

[index_config]
remote_url = "https://github.com/YOUR_USERNAME/YOUR_INDEX.git"
https_username = "YOUR_USERNAME"
https_password = "GITHUB_ACCESS_TOKEN" 
branch = "main"

And run Ktra with passing the path to above file.

ktra -c /path/to/config/your_config.toml

Please remember that Ktra searches ./ktra.toml as a default configuration file if not specified.

Create User And Login

Ktra has several additional web APIs called Ktra Web APIs to manage users.
You should call these APIs to create a new user.

Note:
All APIs are listed and detailed on Appendix: Ktra Web APIs page.

1. Create a new user

Run this command. curl command required.
ALICE just means the first user. Of course you can use a username you like.

curl -X POST -H 'Content-Type: application/json' -d '{"password":"PASSWORD"}' http://localhost:8000/ktra/api/v1/new_user/ALICE

Above command responds and prints a new token like this:

{"token":"TOKEN"}

Please copy TOKEN, the printed token.

2. Login with `cargo` command

Run this command with the TOKEN that you copied.

Note:
ktra in below command is the registry name you specified in .cargo/config.toml file.

cargo login --registry=ktra TOKEN

It's OK if you get this message:

Login token for `ktra` saved

Publish And Use

🎉 Congratulations!
It's time to publish your first and private crate!

1. Create a new crate and publish

Just run:

Note 1:
ktra in below command is the registry name you specified in .cargo/config.toml file.

Note 2:
--allow-dirty option is not needed if your local repository is clean.

cargo new my_crate --lib
cd my_crate
cargo publish --allow-dirty --registry=ktra

If you get no errors your publishing has done perfectly.

2. Use your crate

To use your published crate from another one, you just specify a registry at dependencies section in Cargo.toml.

[package]
name = "my_another_crate"
version = "0.1.0"
authors = ["alice <alice@example.com>"]
edition = "2018"

[dependencies]
my_crate = { version = "0.1", registry = "ktra" }

Appendix: Configurations

Note:
All configurations are able to set via command arguments. See ktra -h for more details.

About Index Configurations

index_config has these configurations:

remote_url
- The essential configuration.
- Sets a URL for the remote index git repository.
local_path
- The default value is ./index
- Sets a path for local index git repository.
branch
- The default value is main.
- Sets a branch name of the index git repository.
https_username
- Required unless you use SSH protocol.
- Sets a username to use for the authentication.
https_password
- Required unless you use SSH protocol.
- Sets a password to use for the authentication.
ssh_privkey_path
- Required unless you use HTTPS protocol.
- Sets a private key path to use for the authentication.
ssh_key_passphrase
- Optional.
- Sets a private key's passphrase to use for authentication if the remote index git repository uses SSH protocol.
ssh_pubkey_path
- Optional.
- Sets a public key path to use for authentication if the remote index git repository uses SSH protocol.
ssh_username
- Optional.
- Sets a username to use for authentication if the remote index git repository uses SSH protocol.
git_email
- The default value is undefined@example.com.
- Sets an author and committer email address.
git_name
- The default value is ktra-driver.
- Sets an author and committer name.

About Crate Files Configurations

crate_files_config is optional and it has these configurations:

dl_dir_path
- The default value is ./crates.
- Sets the crate files directory.
cache_dir_path
- crates-io-mirroring feature needed.
- The default value is ./crates_io_caches.
- Sets the cache files directory.
dl_path
- The default value is ["dl"].
- Sets crate file download paths.
  - Sample: ["path", "to", "download"] to be https://example.com/path/to/download
  - This configuration MUST correspond with the dl field's value in config.json at the index git repository.

About Database Configurations

db_config is optional and it has these configurations:

db_dir_path
- The default value is db if you use db-sled feature.
- Sets a database directory.
redis_url
- The default value is redis://localhost if you use db-redis feature.
- Sets a Redis URL. This can contain a username and password phrase to use the authentication.
mongodb_url
- The default value is redis://localhost:27017 if you use db-mongo feature.
- Sets a Redis URL. This can contain a username and password phrase to use the authentication.
login_prefix
- The default value, for backwards compatible reasons, is ktra-secure-auth:
- Sets a prefix to the usernames in the database/registry.

About Server Configurations

server_config is optional and it has these configurations:

address
- The default value is [0, 0, 0, 0].
- Sets an address HTTP server runs.
port
- The default value is 8000.
- Sets a port number HTTP server listens.

Appendix: Ktra Web APIs

Ktra Web APIs are extra web APIs that are not specified in the specification but required to manage users.
Since all APIs send passwords in cleartext, it is highly recommended that you connect the registry from your local network only OR use an HTTPS connection.

Create a new user

Specification

Endpoint	/ktra/api/v1/new_user/{user_name}
Method	POST
Body	{ "password": "PASSWORD" }

Response

{
    "token": "TOKEN"
}

Login

Specification

Endpoint	/ktra/api/v1/login/{user_name}
Method	POST
Body	{ "password": "PASSWORD" }

Response

{
    "token": "NEW TOKEN"
}

Change password

Specification

Endpoint	/ktra/api/v1/change_password/{user_name}
Method	POST
Body	{ "old_password": "OLD PASSWORD", "new_password": "NEW PASSWORD" }

Response

{
    "token": "NEW TOKEN"
}

Crates.io Mirroring

Note:
This API can be available when crates-io-mirroring feature is enabled.

Specification

Endpoint	/ktra/api/v1/mirror/{crate_name}/{version}/download
Method	GET
Body	-

Response

Binary file.