Getting started

How to build

Before anything, keep in mind that the current minimum supported Rust version for Alexandrie is 1.68 (on stable), make sure to check if your local Rust version is adequate by running rustc -V.

Alexandrie offers multiple options to be used as its database, so before building Alexandrie, you'll need to pick which supported database vendor you wish to use.
The currently supported vendors are:

  • sqlite: for SQLite
  • mysql: for MySQL (including MariaDB)
  • postgres: for PostgreSQL

To build, you can then run:

# navigate to the `crates/alexandrie/` subfolder
cd crates/alexandrie

# build the binary
# (replace `(foo|bar)` occurences by one of `foo` or `bar`)
# (replace `[foo]` occurences by either `foo` or nothing)
cargo build [--release] \
    --no-default-features \
    --features "[frontend] (sqlite|mysql|postgres)"

Before running Alexandrie, you'll need to configure your instance in the alexandrie.toml file.

The database is configured through the [database] table:

[database]
# Replace the '<...>' placeholders by their real actual values.

# For MySQL
url = "mysql://<user>:<password>@<hostname>:<port>/<database>"

# For PostgreSQL
url = "postgresql://<user>:<password>@<hostname>:<port>/<database>"

# For SQLite
url = "<path-to-sqlite-database-file>"
# or:
url = ":memory:" # ephemeral in-memory database, doesn't persists between restarts

Then, you can configure the crates' tarballs storage strategy and the crate index management strategy that you want to use.

Here is an example of how to do it:

[index]
type = "command-line"
path = "crate-index"

[storage]
type = "disk"
path = "crate-storage"

You can find more information about crate index management and crate stores in the 'What's available' section of this book.

You can also configure things like the address and port of the server:

[general]
bind_address = "127.0.0.1:3000"  # The endpoint and port on which to serve the service.

Then, you need to configure a crate index.
A crate index is simply a git repository that the registry uses to keep metadata information about each crate and their individual versions.
The repository can be created on any machine you want, as long as it is reachable from the current machine as a git remote in a clone of that repository.
The remote can be specified using either an HTTPS or SSH link.

If you're using SSH for the remote link, Cargo might have an issue where it can't fetch from the registry's index when doing cargo search or cargo build.
This is because Cargo uses libgit2 to fetch from remotes and fails to find the SSH credentials needed to do so.
To work around this issue, you may need to set the CARGO_NET_GIT_FETCH_WITH_CLI environment variable to true, so that Cargo will offload the fetching from remotes operation to the git command-line utility.
See issue #44 for a previous occurence of this exact issue.

To run the registry with the configuration above, be sure to clone your crate index at the location designated by the path key in [index].
In this case, it is ./crate-index.
To clone an existing crate index, you can run:

# Replace the '<...>' placeholders by their real actual values.
git clone <url-of-the-crate-index> <path-from-config>

# <url-of-the-crate-index>: URL to the git repository serving as the registry's crate index.
# <path-from-config>: Path to the same directory as the one specified as `index.path` in the `alexandrie.toml`.

# Example:
git clone 'https://github.com/Hirevo/alexandrie-index' 'crate-index'

If you want to create one, you can refer to the Cargo's Alternative Registries RFC to learn about the layout of such an index.
You can also visit the crates.io index or the crates.polomack.eu index as deployed examples.

How to run

Once everything is configured, you can run with: cargo run [--release].

Then, if you want to use this index with Cargo, you can follow these steps:

  • Edit or create the ~/.cargo/config file, and add the following code: 
    # Replace the '<...>' placeholders by their real actual values.
[registries.<name-of-your-registry>]
index = "<url-of-the-crate-index>"

# <name-of-your-registry>: A name of your choosing, that you'll be using to refer to it in `cargo` commands.
# <url-of-the-crate-index>: URL to the git repository serving as the registry's crate index.
#                           BE CAREFUL: this is not the URL to the registry's API or frontend.
  • Then, run cargo login --registry <name-of-your-registry> and enter your author token.
    To generate a token, you need to register as an author first. You can do this using the frontend by:
    • Registering at /account/register.
    • Generating a token at /account/manage.
  • You can now use the registry using cargo [search|publish] --registry <name-of-your-registry>

Installation script

If you wish to have a more concrete resource to learn how to setup an Alexandrie instance, like a shell script, you may refer to an example installation script which can help you get started:

https://hirevo.github.io/alexandrie/installation-script.html