HUB
Sign inSign up
stashito logo

rcm7/stashito

By rcm7

•Updated 24 days ago

Free, open-source pull-through cache for Docker/OCI images — pull once, every later pull is local.

Image
0

9.2K

rcm7/stashito repository overview

⁠Stashito

Free, open-source pull-through cache for Docker images. Pull once — every later pull is served from your own disk. No rate limits, no wasted bandwidth, no waiting on the internet.

Works with any OCI registry: Docker Hub, GHCR, Quay, GAR, ACR, ECR.

Stashito is a caching registry proxy — a pull-through cache, or registry mirror. It implements the OCI Distribution Spec, so docker, containerd and podman pull through it unchanged. Use it to dodge Docker Hub rate limits (upstream sees one pull per image), get LAN-speed pulls in CI and homelabs, keep deploys working through registry outages or a dead uplink, and keep images deployable after they vanish upstream: a yanked tag, a deleted repo, a left-pad moment.

https://stashito.com⁠ — full docs at https://stashito.com/llms.txt⁠

Every merge to master is a release. 0 and latest track the newest one, 0.3 and 0.3.1 pin one. Older releases stay pullable at their X.Y.Z tag; the list is at https://github.com/RCM7/stashito/releases⁠. Each tag is a manifest list for linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 and linux/386.

⁠Run it

services:
  stashito:
    image: rcm7/stashito:0
    environment:
      PORT: "8080"
      STORAGE_PATH: "/data/stashito"
      LOG_LEVEL: "info"
      LOG_FORMAT: "text"
      TAG_TTL: "60s"
      UPSTREAM_DOCKERHUB_HOST: "registry-1.docker.io"
    volumes:
      - stashito_data:/data/stashito
    ports:
      - "8080:8080"

volumes:
  stashito_data:

On Kubernetes: helm repo add stashito https://stashito.com/helm-charts, then helm install stashito stashito/stashito. See https://stashito.com/docs/kubernetes⁠.

docker pull localhost:8080/dockerhub/library/postgres:16

The first path segment names an upstream you configured (UPSTREAM_<ALIAS>_HOST, plus _USERNAME / _PASSWORD for private registries). Everything after it is the ordinary image path. AWS ECR hosts are detected automatically; stashito fetches and rotates the ECR authorization token itself, using _USERNAME / _PASSWORD as AWS access keys or, when unset, the AWS default credential chain (IAM role, IRSA). Set MIRROR_UPSTREAM=dockerhub and point the Docker daemon at Stashito with registry-mirrors (or containerd hosts.toml, or a podman mirror): every docker pull postgres is then served from the cache with no image reference changed. Set MAX_STORAGE (e.g. 50GB) to cap the cache: least recently pulled layers are evicted inline so disk use never exceeds it, each pass freeing MAX_STORAGE_HEADROOM (default 10%) below the cap. A blob that does not fit in free disk space is refused with 507 rather than filling the disk.

⁠Metrics

Optional Prometheus metrics: set METRICS_ENABLED=true to expose GET /metrics — cache hits and misses, upstream requests, HTTP latency, storage size and evictions. METRICS_PORT serves them on a separate port. A ready-made Grafana dashboard ships in the repo.

⁠License

GNU AGPL-3.0. Free to use, copy, modify, and distribute. If you run a modified version as a network service, you must offer its source to the users of that service.

Tag summary

Content type

Image

Digest

sha256:2211f8384…

Size

24.1 MB

Last updated

25 days ago

docker pull rcm7/stashito