diff --git a/docs/DOCKER_REGISTRY.md b/docs/DOCKER_REGISTRY.md
new file mode 100644
index 00000000..5e4f8fad
--- /dev/null
+++ b/docs/DOCKER_REGISTRY.md
@@ -0,0 +1,75 @@
+# Using the Local Docker Registry Cache
+
+To avoid Docker Hub rate limits, use our local registry mirror at `10.100.9.70:5000`.
+
+## For Woodpecker CI (Kaniko builds)
+
+In your `.woodpecker.yml`, use these Kaniko flags:
+
+```yaml
+docker-build:
+  image: gcr.io/kaniko-project/executor:debug
+  commands:
+    - /kaniko/executor
+      --context=/woodpecker/src/...
+      --dockerfile=Dockerfile
+      --destination=10.100.9.70:5000/your-image:tag
+      --registry-mirror=10.100.9.70:5000
+      --insecure-registry=10.100.9.70:5000
+      --cache=true
+      --cache-repo=10.100.9.70:5000/your-image/cache
+      --cache-ttl=168h
+```
+
+**Key points:**
+- `--registry-mirror=10.100.9.70:5000` - Pulls base images from local cache
+- `--insecure-registry=10.100.9.70:5000` - Allows HTTP (not HTTPS)
+- `--cache=true` + `--cache-repo=...` - Caches build layers locally
+
+## Available Base Images
+
+The local registry has these cached:
+
+| Image | Tags |
+|-------|------|
+| `node` | `20-slim`, `22-slim`, `22-alpine`, `20-alpine` |
+| `alpine` | `latest` |
+| `nginx` | `alpine` |
+| `bitnami/kubectl` | `latest` |
+| `gcr.io/kaniko-project/executor` | `debug` |
+
+Need a different image? Add it to the cache using crane:
+
+```bash
+kubectl run cache-image --rm -it --restart=Never \
+  --image=gcr.io/go-containerregistry/crane:latest \
+  -- copy docker.io/library/IMAGE:TAG 10.100.9.70:5000/library/IMAGE:TAG --insecure
+```
+
+## DO NOT USE
+
+- ~~`--registry-mirror=mirror.gcr.io`~~ - Rate limited by Docker Hub
+- ~~Direct pulls from `docker.io`~~ - Rate limited (100 pulls/6hr anonymous)
+
+## Checking Cached Images
+
+List all cached images:
+```bash
+curl -s http://10.100.9.70:5000/v2/_catalog | jq
+```
+
+List tags for a specific image:
+```bash
+curl -s http://10.100.9.70:5000/v2/library/node/tags/list | jq
+```
+
+## Troubleshooting
+
+### "no such host" or DNS errors
+The CI runner can't reach the registry mirror. Make sure you're using `10.100.9.70:5000`, not `mirror.gcr.io`.
+
+### "manifest unknown"
+The image/tag isn't cached. Add it using the crane command above.
+
+### HTTP vs HTTPS errors
+Always use `--insecure-registry=10.100.9.70:5000` - the local registry uses HTTP.