Skip to content

README_en.md

Latest commit

 

History

History
124 lines (89 loc) · 3.75 KB

README_en.md

File metadata and controls

124 lines (89 loc) · 3.75 KB

Cloudflare Docker Proxy

English | 简体中文

A high-performance Cloudflare Worker / Pages proxy script for various container registries. It supports dynamic routing configuration via Cloudflare KV backend.

Features

  • Dynamic Routing: Flexible mapping of domains to upstream registries via Cloudflare KV.
  • Multi-Registry Support: Built-in support for Docker Hub, Quay, GCR, GitHub Packages (GHCR), and more.
  • Smart Redirection: Automatically handles Docker Hub official image redirections (e.g., busybox -> library/busybox).
  • Auth Proxy: Supports Docker Hub credentials to resolve 429 Too Many Requests rate limiting.
  • Dual Mode Deployment: Fully supports both Cloudflare Workers and Pages deployment.

Quick Start

Once deployed, simply replace the domain in your docker pull command with your custom domain:

# Original command
docker pull busybox
# Using proxy (assuming your domain is docker.example.com)
docker pull docker.example.com/library/busybox

Deployment Guide

Prerequisites

  1. A Cloudflare account.
  2. Node.js and npm installed locally.

1. Login to Cloudflare

Make sure you are logged in via wrangler:

npx wrangler login

2. Automated Deployment (Recommended)

The project provides a deploy.sh script to automate KV creation, ID synchronization, and mode switching.

Deploy as Workers:

chmod +x deploy.sh
./deploy.sh -m workers

Deploy as Pages:

chmod +x deploy.sh
./deploy.sh -m pages

Note: If you are using a custom config file (e.g., my-config.jsonc), specify it with -c: ./deploy.sh -c my-config.jsonc -m pages.

3. Manual Deployment (Optional)

If you prefer to operate manually, follow these steps:

  1. Create KV Namespace: 
    npx wrangler kv namespace create DOCKER_ROUTES
  2. Update Config: Fill the returned id into the kv_namespaces section of wrangler.jsonc.
  3. Deploy:
    • Workers: npx wrangler deploy
    • Pages: Manually adjust wrangler.jsonc and run npx wrangler pages deploy

Routing Configuration

Configure routes by adding key-value pairs to the KV namespace.

  • Key: Your custom domain (e.g., docker.example.com).
  • Value: Upstream registry URL (e.g., https://registry-1.docker.io).

Add via CLI:

npx wrangler kv key put --binding=DOCKER_ROUTES "docker.example.com" "https://registry-1.docker.io"

Pre-defined Subdomain Routes

For convenience, the Worker automatically matches the following registries based on the subdomain:

Subdomain Upstream Registry
docker https://registry-1.docker.io
quay https://quay.io
gcr https://gcr.io
k8s-gcr https://k8s.gcr.io
k8s https://registry.k8s.io
ghcr https://ghcr.io
cloudsmith https://docker.cloudsmith.io
ecr https://public.ecr.aws

Resolve Docker Hub 429 Rate Limiting

Configure your own Docker Hub credentials to get higher pull quotas:

  1. Create an Access Token in your Docker Hub account settings.

  2. Set encrypted secrets:

    Workers Mode:

    npx wrangler secret put DOCKER_USERNAME
npx wrangler secret put DOCKER_PASSWORD

    Pages Mode:

    npx wrangler pages secret put DOCKER_USERNAME --project-name <YOUR_PROJECT_NAME>
npx wrangler pages secret put DOCKER_PASSWORD --project-name <YOUR_PROJECT_NAME>

Custom Domains

  1. Go to Workers & Pages in your Cloudflare dashboard.
  2. Select your project, go to Settings -> Domains & Routes.
  3. Click Add Custom Domain to bind your domain.

License

This project is open-sourced under the Apache-2.0 License.