You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`enableFrontend`| bool |`true`| Enable web UI (Vue SPA) |
17
17
@@ -22,7 +22,7 @@ Default config path is `./config.toml` in the working directory. Override with `
22
22
|`requestLimit`| int |`500`| Requests per IP per period |
23
23
|`periodHours`| float |`3.0`| Rate limit period (hours) |
24
24
25
-
IPv4 uses full addresses; IPv6 uses `/64` prefixes. Frontend static routes (`/`, `/images`, `/search`, `/assets/*`) are not rate-limited.
25
+
IPv4 uses full addresses; IPv6 uses `/64` prefixes. Only frontend static routes (`/`, `/images`, `/search`, `/favicon.ico`, `/assets/*`) are exempt; `/ready`, API, and proxy requests all count.
26
26
27
27
:::note
28
28
Pulling one Docker image triggers multiple layer requests — each HTTP request counts against the limit.
@@ -69,7 +69,7 @@ Per-registry keys:
69
69
Defaults include `ghcr.io`, `gcr.io`, `quay.io`, `registry.k8s.io`. Docker Hub always proxies to `registry-1.docker.io` and is not configured here.
70
70
71
71
:::note
72
-
All registries currently use anonymous pulls (`authn.Anonymous`). `authType` labels the auth endpoint only — **GitHub tokens and Google service accounts are not yet implemented**. Private images require client-side authentication.
72
+
All registries currently use anonymous pulls (`authn.Anonymous`). `authType` labels the auth endpoint only — **GitHub tokens and Google service accounts are not yet implemented**, and client `Authorization` headers are not forwarded. **Private authenticated images cannot be pulled through HubProxy.**
73
73
:::
74
74
75
75
## [tokenCache]
@@ -93,7 +93,7 @@ Upstream token `expires_in` is used for token cache (5-minute safety margin, min
93
93
94
94
| Path | Description |
95
95
|------|-------------|
96
-
|`GET /ready`| Health check — returns `ready`, `version`, `uptime_sec`, etc. |
96
+
|`GET /ready`| Health check — returns `ready`, `version`, `uptime_sec`, etc. (**counts toward** rate limit) |
Copy file name to clipboardExpand all lines: docs/src/content/docs/en/faq.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,7 +20,7 @@ Strongly recommended. It provides TLS, correct client IP passing, and avoids exp
20
20
<details>
21
21
<summary>What's the difference between rate-limit and registry whitelists?</summary>
22
22
23
-
`[security].whiteList` exempts IPs from rate limiting. `[access].whiteList` controls which Docker images and GitHub repos can be proxied. They are independent.
23
+
`[security].whiteList` exempts IPs from rate limiting. `[access].whiteList` controls which Docker images, GitHub repos, and Hugging Face resources can be proxied. They are independent.
24
24
25
25
</details>
26
26
@@ -55,7 +55,7 @@ If HubProxy connects directly to Cloudflare edges, rate limits apply per Cloudfl
55
55
<details>
56
56
<summary>How do I verify the service is running?</summary>
57
57
58
-
Visit `https://example.com/ready` — a healthy response includes `ready`, `service`, `version`, and `uptime_sec`.
58
+
Visit `https://example.com/ready` — a healthy response includes `ready`, `service`, `version`, and `uptime_sec`. This path **counts toward** the IP rate limit; avoid high-frequency polling.
59
59
60
60
</details>
61
61
@@ -87,6 +87,6 @@ Add a regex to `githubExps` in `src/handlers/github.go`. See [Development & Buil
87
87
<details>
88
88
<summary>Why can't I pull private images with authType github?</summary>
89
89
90
-
`authType` labels auth endpoints only — credential injection is not yet implemented. All registry pulls use anonymous auth. Use client-side `docker login` for private images.
90
+
`authType` labels auth endpoints only — credential injection is not yet implemented. All registry pulls use anonymous auth and client`Authorization` headers are not forwarded. **Private authenticated images cannot be pulled through HubProxy.**
Copy file name to clipboardExpand all lines: docs/src/content/docs/en/guides/docker-mirror-sources.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,7 +45,7 @@ enabled = true
45
45
|`quay`| Quay.io auth endpoint |
46
46
47
47
:::note
48
-
`authType` matches upstream token auth endpoints only. The current version does **not** inject GitHub tokens or Google service accounts — all pulls use anonymous auth. Private images require client-side `docker login`.
48
+
`authType` matches upstream token auth endpoints only. The current version does **not** inject GitHub tokens or Google service accounts — all pulls use anonymous auth and client credentials are not forwarded. **Private authenticated images cannot be pulled.**
Copy file name to clipboardExpand all lines: docs/src/content/docs/en/guides/offline-images.mdx
+29-5Lines changed: 29 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,31 @@ Downloads use a **two-step flow**: `prepare` for a one-time token, then download
9
9
10
10
## Web UI
11
11
12
-
Visit the HubProxy homepage and use the offline image feature. When selecting an architecture, if the image does not provide the selected architecture or the input is invalid, it automatically falls back to `linux/amd64`.
12
+
Visit the HubProxy homepage and use the offline image feature. Leave architecture empty to prefer `linux/amd64`; if a specified architecture is unmatched, the first available platform in the multi-arch index is used.
13
+
14
+
## Image Reference Format
15
+
16
+
Besides Docker Hub official images, enter a full registry-prefixed reference to pull from other platforms:
Missing tags default to `:latest`. Single-segment names (no `/`) get the `library/` namespace. The registry must be enabled in `[registries]` and the image must be anonymously pullable.
26
+
27
+
## Compressed Layers
28
+
29
+
The web UI and API expose a compressed-layers toggle (`compressed` / `useCompressedLayers`, **on by default**). **Keep it enabled** in most cases.
30
+
31
+
| Setting | Contents of each `layer.tar` in the archive | Size | Use case |
| On (default) |**Compressed blob** from the registry (usually gzip) | Smaller, faster download | Modern Docker Engine, `docker load`|
34
+
| Off |**Uncompressed** filesystem layer tar (classic `docker save` format) | Larger, slower to build | Older Docker Engine versions or environments that only accept uncompressed layers |
35
+
36
+
HubProxy outputs a `docker load`-compatible tar. With compression enabled, each layer keeps the upstream compressed blob instead of decompressing and re-packing on the server, which saves bandwidth and CPU. The off switch remains for **legacy Docker** (image format v1 era and early `docker load` implementations): those expect uncompressed filesystem tars in `layer.tar`, matching `docker save` output — disabling compression produces the same layer format.
13
37
14
38
## Single Image API
15
39
@@ -37,9 +61,9 @@ Optional parameters:
37
61
38
62
| Param | Description |
39
63
|-------|-------------|
40
-
|`platform`| Target platform, e.g. `linux/arm64`; falls back to `linux/amd64` if unmatched or invalid|
64
+
|`platform`| Target platform, e.g. `linux/arm64`; empty prefers `linux/amd64`; if specified but unmatched, uses the first available platform in the index|
41
65
|`tag`| Used when image has no tag, default `latest`|
42
-
|`compressed`|Compress layers, default `true`|
66
+
|`compressed`|Keep registry-compressed layers in tar, default `true` (recommended — see **Compressed Layers** above)|
43
67
44
68
## Batch API
45
69
@@ -48,7 +72,7 @@ Optional parameters:
48
72
```bash
49
73
curl -X POST "https://example.com/api/image/batch?mode=prepare" \
0 commit comments