Skip to content

Quickstart

  1. Install

    With Podman:

    Terminal window
    podman run -p 8346:8346 -v vein-data:/data ghcr.io/contriboss/vein:latest

    Or build from source:

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

    Vein needs a Postgres database to connect to.

  2. Initialize a config

    Terminal window
    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 = "postgres://user:pass@localhost/vein" # or set VEIN_DATABASE_URL
    # Optional: enable RubyGems fetching for uncached gems.
    # crates.io and npm work without any upstream config.
    # [upstream]
    # url = "https://rubygems.org"
  3. Run

    Terminal window
    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). Vein’s homepage (/) prints these same commands with the URL you opened it at.

    Terminal window
    # Bundler (RubyGems): mirror rubygems.org, Gemfiles unchanged
    bundle config set --global mirror.https://rubygems.org http://localhost:8346
    # npm
    npm config set registry http://localhost:8346/

    Cargo replaces crates.io through source replacement, in ~/.cargo/config.toml (or a project’s .cargo/config.toml):

    [source.crates-io]
    replace-with = "vein"
    [source.vein]
    registry = "sparse+http://localhost:8346/index/"
  5. Check it’s alive

    Terminal window
    cargo run -- health
    # or
    curl http://localhost:8346/up
  1. Client requests a package (gem, crate, or npm tarball).
  2. Vein checks its Postgres 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.