Documentation

Core

These topics apply to peryx whatever it serves. The ecosystems each build on them with their own protocol, clients, and workflows.

  • Installation

    The install channels, the platforms each covers, and how each one updates.

  • When to use peryx (and when not)

    The problems a read-through cache and private index solves for any ecosystem, and the honest list of problems it does not.

  • Architecture

    How one process serves a pull: the request path, the streaming cache, freshness, and the two stores.

  • Configuration

    Every TOML key, flag, and default. Precedence is defaults < TOML file < environment < flags.

  • Getting started

    Install peryx, start it with no configuration, then continue with the ecosystem you serve: PyPI or OCI.

  • Performance and methodology

    Why a peryx cache keeps up with the upstream on a miss and pulls ahead when warm, how it is measured, and the per-operation cost of each ecosystem's driver.

  • API explorer

    Per-endpoint request and response breakdown with copyable examples, generated from the code.

  • The index model

    Cached, hosted, and virtual indexes across ecosystems: how composition works, why shadowing is the dependency-confusion fix, and what removal means.

  • Command line

    The peryx binary's commands and flags.

  • Standards

    How peryx relates to the interoperability standards each ecosystem defines, and where the per-ecosystem specs live.

  • Capability matrix

    Which roles and cross-cutting features peryx supports per ecosystem, plus what each ecosystem implements of its own protocol.

  • Glossary (FAQ)

    Plain-language answers to the cross-cutting terms peryx uses: index, cached/hosted/virtual, ecosystem, shadowing, upstream, publish, artifact.

  • Use the web UI

    Search packages, browse indexes, read package pages, inspect status, and inspect archives from the browser.

  • Monitor usage and cache health

    Read the usage counters, drill down to files, watch for upstream changes, and scrape Prometheus.

  • Configure logging

    Choose a level, a format, and a sink: stdout, rotating file, journald, or syslog.

  • Serve HTTPS

    Turn on TLS with a certificate you provide, an automatic Let's Encrypt certificate, or a reverse proxy that terminates TLS.