stage pullthru cache post

blog/2025-02-25-pullthru-cache/index.mdx

@@ -0,0 +1,184 @@
+---
+slug: pullthru-cache
+title: Setting up a Docker Hub pull-through cache with Tigris
+description: >
+  A pull-through cache is a local cache of Docker images that can be used to
+  speed up deployments and defend against the upcoming rate limit decreases for
+  the Docker Hub. Learn how to make one on top of Tigris!
+image: ./prone-tiger-vibe.webp
+keywords: [docker, docker hub, pull-through cache]
+authors: [xe]
+tags: [docker, tigris]
+---
+
+import InlineCta from "@site/src/components/InlineCta";
+
+The Docker Hub is going to drastically decrease the rate limits for free
+accounts on April first. Are you ready for those changes? Here’s a high level
+overview of
+[the rate limit changes we’re about to have](https://docs.docker.com/docker-hub/usage/):
+
+| Account type          | Old rate limit           | New rate limit (April 1st)                                    |
+| :-------------------- | :----------------------- | :------------------------------------------------------------ |
+| Free, authenticated   | 200 image pulls per hour | 100 image pulls per hour                                      |
+| Free, unauthenticated | 100 image pulls per hour | 10 image pulls per hour (per IPv4 address or IPv6 /64 subnet) |
+
+What if you could easily cache images so these rate limits don’t impact your
+workloads? Today I’m going to show you how you can set up your own pull-through
+cache of the docker hub so that your workloads only have to download images
+once.
+
+{/* truncate */}
+
+![A prone cartoon tiger vibing on a pier with coffee](./prone-tiger-vibe.webp)
+
+<center>
+  <small>
+    <em>
+      A prone cartoon tiger vibing on a pier with coffee. Image generated using
+      Pony Diffusion v6.
+    </em>
+  </small>
+</center>
+
+## Pull-through caches and you
+
+When you start an app in a Docker image, the Docker daemon needs to pull the
+image to your server before it can run. Normally this is done by directly
+connecting to the registry containing the image (such as the Docker Hub), asking
+for a list of image blobs, and then downloading all the blobs.
+
+<div
+  style={{
+    marginLeft: "auto",
+    marginRight: "auto",
+    marginTop: "0.25rem",
+    marginBottom: "0.25rem",
+    backgroundColor: "white",
+    paddingTop: "0.5rem",
+    paddingBottom: "0.5rem",
+    borderRadius: "0.5rem",
+  }}
+>
+  <center>![](./normal-pull.webp)</center>
+</div>
+
+When you configure your Docker daemon to use a pull-through cache for a
+registry, the process changes a little. Instead of contacting the registry
+directly, your Docker daemon asks the pull-through cache if it has the image
+cached. If it does, you pull the image from the cache and avoid using part of
+your rate limit.
+
+<div
+  style={{
+    marginLeft: "auto",
+    marginRight: "auto",
+    marginTop: "0.25rem",
+    marginBottom: "0.25rem",
+    backgroundColor: "white",
+    paddingTop: "0.5rem",
+    paddingBottom: "0.5rem",
+    borderRadius: "0.5rem",
+  }}
+>
+  <center>![](./cache-hit.webp)</center>
+</div>
+
+What happens when the image isn’t cached? The pull-through cache will query the
+upstream registry to see if the image exists. If it doesn’t, the error is
+propagated back to the Docker daemon.
+
+<div
+  style={{
+    marginLeft: "auto",
+    marginRight: "auto",
+    marginTop: "0.25rem",
+    marginBottom: "0.25rem",
+    backgroundColor: "white",
+    paddingTop: "0.5rem",
+    paddingBottom: "0.5rem",
+    borderRadius: "0.5rem",
+  }}
+>
+  <center>![](./cache-miss.webp)</center>
+</div>
+
+But if it does, the registry responds with a list of blobs and the pull-through
+cache starts downloading them. As the blobs get downloaded, they get forwarded
+to the Docker daemon as well.
+
+<div
+  style={{
+    marginLeft: "auto",
+    marginRight: "auto",
+    marginTop: "0.25rem",
+    marginBottom: "0.25rem",
+    backgroundColor: "white",
+    paddingTop: "0.5rem",
+    paddingBottom: "0.5rem",
+    borderRadius: "0.5rem",
+  }}
+>
+  <center>![](./cache-download.webp)</center>
+</div>
+
+This lets you continue using the Docker Hub as normal, but you don’t need to
+authenticate every server with an account. When you store your cached images in
+Tigris, you also can take advantage of Tigris’ global architecture to make sure
+that the images are as close to your servers as possible.
+
+## Setting one up
+
+You can set up your own pull-through cache of the docker hub in minutes with our
+[example on GitHub](https://github.com/tigrisdata-community/pull-thru-docker-hub).
+All you need is the following:
+
+- A free Tigris account on [https://storage.new](https://storage.new)
+- A Tigris bucket
+- A Tigris [authentication keypair](https://console.tigris.dev/createaccesskey)
+- A user account on the Docker Hub
+- A server with
+  [Docker and Docker Compose installed](https://docs.docker.com/engine/install/ubuntu/)
+  or a Kubernetes cluster with HTTP ingress set up (such as with
+  [k3s](https://k3s.io) and
+  [Traefik](https://docs.k3s.io/networking/networking-services#traefik-ingress-controller))
+
+From there, you prepare the environment configuration, edit some settings, and
+apply the configs. You can use it in your systems (such as the Docker daemon or
+k3s) by pointing to the pull-through cache server. Here’s how you do it on a
+Linux machine running the Docker daemon:
+
+- Open `/etc/docker/daemon.json` in a text editor as root
+- Add the HTTPS url of your pull-through cache server to the `registry-mirrors`
+  key like this:
+
+```json
+{
+  "registry-mirrors": ["https://dockerhub.yourdomain.example"]
+}
+```
+
+After you restart the Docker daemon (`sudo systemctl restart docker`), any time
+you pull an image from the Docker Hub it’ll automatically be cached and pulled
+from Tigris instead.
+
+## Conclusion
+
+Once you’ve set up a cache like this, you don’t have to worry about the Docker
+hub rate limit changes again. If you run into rate limits that start impacting
+your operations, you only need to update that one account that’s used to do all
+the pulls for your pull-through cache. This lets you get the best of both
+worlds: all your machines will be protected from the changes to rate limits and
+you don’t have to distribute a password to all your systems or developer
+machines.
+
+Want to give this a try? Create an account on Tigris and follow
+[the instructions on GitHub](https://github.com/tigrisdata-community/pull-thru-docker-hub)!
+
+<InlineCta
+  title={"Want to try Tigris?"}
+  subtitle={
+    "Make a bucket and store your Docker images across the globe without egress fees!"
+  }
+  button={"Get started with Tigris!"}
+/>