🚚 The Ktra Book
Your Little Cargo Registry.
Sections
About Ktra
To know about Ktra
.
Installation
To install Ktra
.
Quick Start
To start Ktra
quickly.
Appendices
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.
When I/we need Ktra
?
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.
- via
- Redis support.
- via
db-redis
feature.
- via
- MongoDB support.
- via
db-mongo
feature.
- via
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
Tags
There are several images tagged with features and releases.
Any commit on develop
branch builds images listed below:
latest
db-sled
featured image.
db-redis-latest
db-redis
featured image.
db-mongo-latest
db-mongo
featured image.
Similarly, images below are built automatically when tags are pushed:
{VERSION}
(e.g.0.4.3
)db-sled
featured image.
db-redis-{VERSION}
db-redis
featured image.
db-mongo-{VERSION}
db-mongo
featured image.
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 onGitHub
butGitLab
,Bitbucket
and other git repository hosting services might default tomaster
instead ofmain
.
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 onGitHub
butGitLab
,Bitbucket
and other git repository hosting services might default tomaster
instead ofmain
.
[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. Seektra -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.
- The default value is
branch
- The default value is
main
. - Sets a branch name of the index git repository.
- The default value is
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.
- The default value is
git_name
- The default value is
ktra-driver
. - Sets an author and committer name.
- The default value is
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.
- The default value is
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 behttps://example.com/path/to/download
- This configuration MUST correspond with the
dl
field's value inconfig.json
at the index git repository.
- Sample:
- The default value is
About Database Configurations
db_config
is optional and it has these configurations:
db_dir_path
- The default value is
db
if you usedb-sled
feature. - Sets a database directory.
- The default value is
redis_url
- The default value is
redis://localhost
if you usedb-redis
feature. - Sets a Redis URL. This can contain a username and password phrase to use the authentication.
- The default value is
mongodb_url
- The default value is
redis://localhost:27017
if you usedb-mongo
feature. - Sets a Redis URL. This can contain a username and password phrase to use the authentication.
- The default value is
login_prefix
- The default value, for backwards compatible reasons, is
ktra-secure-auth:
- Sets a prefix to the usernames in the database/registry.
- The default value, for backwards compatible reasons, is
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.
- The default value is
port
- The default value is
8000
. - Sets a port number HTTP server listens.
- The default value is
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.