Quickstart

1. Install

   With Docker:

   docker run -p 8346:8346 -v vein-data:/data ghcr.io/contriboss/vein:latest

   Or build from source (SQLite backend, default):

   git clone https://github.com/contriboss/vein.git
   cd vein
   cargo build --release

   For a PostgreSQL backend instead of SQLite:

   cargo build --release --no-default-features --features postgres,tls

   SQLite and PostgreSQL are mutually exclusive at compile time - pick one.

2. Initialize a config

   cargo run -- init

   This writes vein.toml. A minimal config looks like:

   [server]
   host = "0.0.0.0"
   port = 8346
   
   [storage]
   path = "./cache"
   
   [database]
   url = "sqlite://./vein.db"
   
   # Optional: enable RubyGems fetching for uncached gems.
   # crates.io and npm work without any upstream config.
   # [upstream]
   # url = "https://rubygems.org"

3. Run

   cargo run -- serve --config vein.toml
   # or, once built:
   ./target/release/vein serve --config vein.toml

4. Point clients at it

   All three ecosystems share the same base URL (http://localhost:8346 here):

   # Bundler (RubyGems)
   bundle config mirror.https://rubygems.org http://localhost:8346
   
   # Cargo (crates.io sparse index)
   export CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse
   export CARGO_REGISTRIES_CRATES_IO_INDEX=http://localhost:8346/index/
   
   # npm
   npm config set registry http://localhost:8346/

5. Check it’s alive

   cargo run -- health
   # or
   curl http://localhost:8346/up

What happens on a request

1. Client requests a package (gem, crate, or npm tarball).
2. Vein checks its SQLite/PostgreSQL metadata store for a cache hit.
3. Hit - served straight from local filesystem storage.
4. Miss - fetched from the upstream (RubyGems, crates.io, or npm), cached, then served.

Index and metadata endpoints are cached with a TTL and revalidated; artifact files are cached permanently once fetched.

See Architecture for the storage model, CLI for the full command list, and Configuration for every config option.