An alternate cargo registry suitable for small-scale crate publishing and distribution.
An estuary is a coastal semi-enclosed body of water where fresh and salt waters meet.
Apparently the blue crab calls this sort of environment home.
The high-level mission here is to provide a rust package registry in the same vein as devpi (for python packages) or verdaccio (for npm packages).
Estuary aims to be a lightweight cargo registry for internal/private use.
Devpi and Verdaccio both offer a rich set of features including search, passive upstream index mirroring and even nice a web UI.
Today, Estuary only supports the most fundamental registry functions:
These features allow us to cargo install
or use crates from the registry as
dependencies in other crates.
Estuary does not yet implement any sort of authentication handling and as such is only appropriate for internal use.
$ cargo install estuary
Support for loading environment variables from a .env
file (off by default)
can be added with:
$ cargo install estuary --features dotenv
Estuary depends on being able to run git
on the command-line.
For a full list of configuration options, run estuary --help
.
Estuary allows for configuration to be specified by either flags on the command line, or from environment variables.
Required Configuration:
--base-url
/ESTUARY_BASE_URL
Public URL for the Estuary server, ex: http://estuary.example.com
.--crate-dir
/ESTUARY_CRATE_DIR
Path to store crate files.--index-dir
/ESTUARY_INDEX_DIR
Path to store the git repository (used to manage the package index).Note: Estuary relies on being able to run
git
on the command line, and expects to be able to findgit
in thePATH
. If for some reason you're running Estuary in an environment where this is not the case, you should specify a path to thegit
binary with--git-bin
orESTUARY_GIT_BIN
.
An example Dockerfile is included in the repo and may serve as a good quickstart guide for deploying Estuary.
To use the example Dockerfile as-is, you can build and run it like so:
# Build the image
docker build -t estuary-quickstart -f example.Dockerfile .
# You'll want to pick a more permanent spot, but this is our volume for package
# and index data.
mkdir /tmp/estuary-data
# Run the image, specifying the port-mapping, volume mount, and base-url
docker run --rm -it -p 1234:7878 -v /tmp/estuary-data:/var/lib/estuary \
estuary-quickstart \
--base-url=http://localhost:1234
Estuary exposes its package index git repository at the following URL:
<base-url>/git/index
To use Estuary for publishing or installing crates via cargo you need to add some configuration.
For example, if you defined your base url as http://estuary.example.com
,
you would add the following to your .cargo/config.toml
:
[registries]
estuary = { index = "http://estuary.example.com/git/index" }
With this entry added to your config, the next step is to "authenticate."
$ cargo login --registry estuary
Note that Estuary currently does nothing with the token to validate access. The token currently means nothing, yet cargo requires it.
From here, you can publish crates to Estuary with
$ cargo publish --registry estuary
You may want to add a
publish
field to your private packages to ensure they aren't accidentally published to crates.io.
Crates published to Estuary can be listed as dependencies in other crates by specifying the registry name like so:
[dependencies]
my-cool-package = { version = "1.2.3", registry = "estuary" }
Binary crates can also be installed using the --registry
flag:
$ cargo install --registry estuary my-cool-app
Environment variables can also be used to configure cargo. See the docs on using an alternate registry and publishing to an alternate registry for more on this.
Small release to fix a highly embarrassing bug 😅. Since the issue drastically limits the usefulness of Estuary, v0.1.0 will be yanked.
Fixed:
Initial Release!
This release is very bare bones, offering only the most essential registry features to allow you to publish and download crates.