How-to guides

Use these guides after choosing an OCI index role and route.

• Cache images for CI

  Cache Docker Hub base images for CI runners and reduce anonymous upstream pulls.

• Compose a virtual registry

  Stack a hosted store over a cached Docker Hub proxy so your own images shadow same-named upstream ones, the dependency-confusion defense for containers.

• Mirror Docker Hub official images

  Pull Docker Hub official images through a routed proxy and configure library_prefix.

• Proxy a private registry

  Cache a private or authenticated upstream registry (GHCR, ECR, Harbor, or an Artifactory /v2/) through peryx, supplying upstream credentials.

• Private OCI indexes and scoped tokens

  Token signing, repository-scoped grants, expiry, catalog access, and server-wide anonymous-read policy.

• Work with registry behavior

  Proxy non-sha256 manifests and cancel or resume OCI blob uploads.

• Serve images air-gapped

  Run peryx as a container registry with no path to Docker Hub by pre-seeding a cache or carrying the data directory across the gap.

• Store Helm charts, SBOMs, and signatures

  Use a hosted OCI index to push Helm charts and arbitrary artifacts, then attach and discover SBOMs and signatures through the referrers API.

• Run a container registry

  Proxy Docker Hub, host your own images, and shadow upstream with a virtual index, then pull and push with docker, podman, or crane.

• Use a local HTTP registry

  Why loopback container registries work over HTTP and what changes across a VM or network boundary.

• Troubleshoot Docker and Podman

  Diagnose token challenges, missing manifests, push limits, and availability retries.