docs: document native chunked registry push and Cloudflare compatibility
- commit
- f6e6249a80b21dcecffa638f1a6bc62085157d36
- author
- brice · · 2026-03-14 14:11 UTC
- parent
- c062834
- signature
- unsigned
3 files · +13 -2
M docs/cli/attachments.md +5 -0
| @@ -159,6 +159,11 @@ gordon attachments push <image> [options] | |||
| 159 | 159 | ||
| 160 | 160 | `gordon attachments push` pushes attachment images such as databases and caches to the Gordon registry so they are available when routes deploy. It does not trigger deployment. The image must already be configured as an attachment first. | |
| 161 | 161 | ||
| 162 | + | It uses the same native chunked upload transport as `gordon push`, sending image | |
| 163 | + | layers in 50MB chunks so pushes work through Cloudflare-proxied Gordon | |
| 164 | + | instances. Keep the server's `max_blob_chunk_size` larger than the client chunk | |
| 165 | + | size; the default `95MB` is compatible. | |
| 166 | + | ||
| 162 | 167 | ### Examples | |
| 163 | 168 | ||
| 164 | 169 | ```bash | |
| @@ -159,6 +159,11 @@ gordon attachments push <image> [options] | |||||
| 159 | 159 | ||||
| 160 | `gordon attachments push` pushes attachment images such as databases and caches to the Gordon registry so they are available when routes deploy. It does not trigger deployment. The image must already be configured as an attachment first. | 160 | `gordon attachments push` pushes attachment images such as databases and caches to the Gordon registry so they are available when routes deploy. It does not trigger deployment. The image must already be configured as an attachment first. | ||
| 161 | 161 | ||||
| 162 | + | It uses the same native chunked upload transport as `gordon push`, sending image | |||
| 163 | + | layers in 50MB chunks so pushes work through Cloudflare-proxied Gordon | |||
| 164 | + | instances. Keep the server's `max_blob_chunk_size` larger than the client chunk | |||
| 165 | + | size; the default `95MB` is compatible. | |||
| 166 | + | ||||
| 162 | ### Examples | 167 | ### Examples | ||
| 163 | 168 | ||||
| 164 | ```bash | 169 | ```bash | ||
M docs/cli/push.md +5 -0
| @@ -72,6 +72,11 @@ gordon push myapp.example.com --build -f docker/app/Dockerfile | |||
| 72 | 72 | - `gordon push` still requires the route to already exist so it can resolve the target image. | |
| 73 | 73 | - `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux, | |
| 74 | 74 | install the `docker-buildx-plugin` package. | |
| 75 | + | - Gordon uses native registry uploads instead of shelling out to `docker push`. | |
| 76 | + | Image layers are sent in 50MB chunks, which stays under Cloudflare's 100MB | |
| 77 | + | per-request limit so proxied pushes keep working. Keep the server's | |
| 78 | + | `max_blob_chunk_size` larger than the client chunk size; the default `95MB` | |
| 79 | + | works out of the box. | |
| 75 | 80 | ||
| 76 | 81 | ## Related | |
| 77 | 82 | ||
| @@ -72,6 +72,11 @@ gordon push myapp.example.com --build -f docker/app/Dockerfile | |||||
| 72 | - `gordon push` still requires the route to already exist so it can resolve the target image. | 72 | - `gordon push` still requires the route to already exist so it can resolve the target image. | ||
| 73 | - `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux, | 73 | - `--build` requires Docker with Buildx. Docker Desktop includes it; on Linux, | ||
| 74 | install the `docker-buildx-plugin` package. | 74 | install the `docker-buildx-plugin` package. | ||
| 75 | + | - Gordon uses native registry uploads instead of shelling out to `docker push`. | |||
| 76 | + | Image layers are sent in 50MB chunks, which stays under Cloudflare's 100MB | |||
| 77 | + | per-request limit so proxied pushes keep working. Keep the server's | |||
| 78 | + | `max_blob_chunk_size` larger than the client chunk size; the default `95MB` | |||
| 79 | + | works out of the box. | |||
| 75 | 80 | ||||
| 76 | ## Related | 81 | ## Related | ||
| 77 | 82 | ||||
M docs/config/server.md +3 -2
| @@ -220,8 +220,9 @@ max_blob_chunk_size = "1GB" # Allow larger layers | |||
| 220 | 220 | ||
| 221 | 221 | **Behavior:** | |
| 222 | 222 | - When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large` | |
| 223 | - | - Docker/Podman may send a full layer in one request, so set this high enough for your base images | |
| 224 | - | - Default (`95MB`) is compatible with Cloudflare and most CDN proxies; increase if pushing very large layers directly | |
| 223 | + | - Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request | |
| 224 | + | - Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (`95MB`) is fine | |
| 225 | + | - Increase it only if you expect larger direct registry uploads from other clients | |
| 225 | 226 | ||
| 226 | 227 | ## Registry IP Allowlist | |
| 227 | 228 | ||
| @@ -220,8 +220,9 @@ max_blob_chunk_size = "1GB" # Allow larger layers | |||||
| 220 | 220 | ||||
| 221 | **Behavior:** | 221 | **Behavior:** | ||
| 222 | - When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large` | 222 | - When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large` | ||
| 223 | - | - Docker/Podman may send a full layer in one request, so set this high enough for your base images | 223 | + | - Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request |
| 224 | - | - Default (`95MB`) is compatible with Cloudflare and most CDN proxies; increase if pushing very large layers directly | 224 | + | - Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (`95MB`) is fine |
| 225 | + | - Increase it only if you expect larger direct registry uploads from other clients | |||
| 225 | 226 | ||||
| 226 | ## Registry IP Allowlist | 227 | ## Registry IP Allowlist | ||
| 227 | 228 | ||||