mirror of
https://github.com/ipfs/kubo.git
synced 2026-03-11 03:09:41 +08:00
docs: add production deployment guidance for gateway (#11117)
- add "Running in Production" section to gateway.md - link to specs.ipfs.tech instead of github - update "Protocol Labs" to "IPFS Foundation" - add reverse proxy requirement to config.md PublicGateways section - reference reverse proxy, timeout, rate limiting, and CDN caveats
This commit is contained in:
Marcin Rataj
GitHub
parent
23ba660ef0
commit
3e85793b58
@ -1073,7 +1073,11 @@ Toggle and configure experimental features of Kubo. Experimental features are li
|
||||
|
||||
Options for the HTTP gateway.
|
||||
|
||||
**NOTE:** support for `/api/v0` under the gateway path is now deprecated. It will be removed in future versions: <https://github.com/ipfs/kubo/issues/10312>.
|
||||
> [!IMPORTANT]
|
||||
> By default, Kubo's gateway is configured for local use at `127.0.0.1` and `localhost`.
|
||||
> To run a public gateway, configure your domain names in [`Gateway.PublicGateways`](#gatewaypublicgateways).
|
||||
> For production deployment considerations (reverse proxy, timeouts, rate limiting, CDN),
|
||||
> see [Running in Production](gateway.md#running-in-production).
|
||||
|
||||
### `Gateway.NoFetch`
|
||||
|
||||
@ -1268,6 +1272,11 @@ Examples:
|
||||
- `*.example.com` will match requests to `http://foo.example.com/ipfs/*` or `http://{cid}.ipfs.bar.example.com/*`.
|
||||
- `foo-*.example.com` will match requests to `http://foo-bar.example.com/ipfs/*` or `http://{cid}.ipfs.foo-xyz.example.com/*`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Reverse Proxy:** If running behind nginx or another reverse proxy, ensure
|
||||
> `Host` and `X-Forwarded-*` headers are forwarded correctly.
|
||||
> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) in gateway documentation.
|
||||
|
||||
#### `Gateway.PublicGateways: Paths`
|
||||
|
||||
An array of paths that should be exposed on the hostname.
|
||||
@ -1334,6 +1343,9 @@ Default: `false`
|
||||
|
||||
Type: `bool`
|
||||
|
||||
> [!IMPORTANT]
|
||||
> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy.
|
||||
|
||||
#### `Gateway.PublicGateways: NoDNSLink`
|
||||
|
||||
A boolean to configure whether DNSLink for hostname present in `Host`
|
||||
@ -1344,6 +1356,9 @@ Default: `false` (DNSLink lookup enabled by default for every defined hostname)
|
||||
|
||||
Type: `bool`
|
||||
|
||||
> [!IMPORTANT]
|
||||
> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy.
|
||||
|
||||
#### `Gateway.PublicGateways: InlineDNSLink`
|
||||
|
||||
An optional flag to explicitly configure whether subdomain gateway's redirects
|
||||
@ -1411,6 +1426,9 @@ ipfs config --json Gateway.PublicGateways '{"localhost": null }'
|
||||
|
||||
Below is a list of the most common gateway setups.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy.
|
||||
|
||||
- Public [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://{cid}.ipfs.dweb.link` (each content root gets its own Origin)
|
||||
|
||||
```console
|
||||
|
||||
@ -6,7 +6,7 @@ they were stored in a traditional web server.
|
||||
|
||||
[More about Gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/) and [addressing IPFS on the web](https://docs.ipfs.tech/how-to/address-ipfs-on-web/).
|
||||
|
||||
Kubo's Gateway implementation follows [ipfs/specs: Specification for HTTP Gateways](https://github.com/ipfs/specs/tree/main/http-gateways#readme).
|
||||
Kubo's Gateway implementation follows [IPFS Gateway Specifications](https://specs.ipfs.tech/http-gateways/) and is tested with [Gateway Conformance Test Suite](https://github.com/ipfs/gateway-conformance).
|
||||
|
||||
### Local gateway
|
||||
|
||||
@ -14,14 +14,21 @@ By default, Kubo nodes run
|
||||
a [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://127.0.0.1:8080/`
|
||||
and a [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://localhost:8080/`.
|
||||
|
||||
The path one also implements [trustless gateway spec](https://specs.ipfs.tech/http-gateways/trustless-gateway/)
|
||||
and supports [trustless responses](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) as opt-in via `Accept` header.
|
||||
> [!CAUTION]
|
||||
> **For browsing websites, web apps, and dapps in a browser, use the subdomain
|
||||
> gateway** (`localhost`). Each content root gets its own
|
||||
> [web origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy),
|
||||
> isolating localStorage, cookies, and session data between sites.
|
||||
>
|
||||
> **For file retrieval, use the path gateway** (`127.0.0.1`). Path gateways are
|
||||
> suited for downloading files or fetching [verifiable](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval)
|
||||
> content, but lack origin isolation (all content shares the same origin).
|
||||
|
||||
Additional listening addresses and gateway behaviors can be set in the [config](#configuration) file.
|
||||
|
||||
### Public gateways
|
||||
|
||||
Protocol Labs provides a public gateway at
|
||||
IPFS Foundation [provides public gateways](https://docs.ipfs.tech/concepts/public-utilities/) at
|
||||
`https://ipfs.io` ([path](https://specs.ipfs.tech/http-gateways/path-gateway/)),
|
||||
`https://dweb.link` ([subdomain](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway)),
|
||||
and `https://trustless-gateway.link` ([trustless](https://specs.ipfs.tech/http-gateways/trustless-gateway/) only).
|
||||
@ -41,6 +48,80 @@ The gateway's log level can be changed with this command:
|
||||
> ipfs log level core/server debug
|
||||
```
|
||||
|
||||
## Running in Production
|
||||
|
||||
When deploying Kubo's gateway in production, be aware of these important considerations:
|
||||
|
||||
<a id="reverse-proxy"></a>
|
||||
> [!IMPORTANT]
|
||||
> **Reverse Proxy:** When running Kubo behind a reverse proxy (such as nginx),
|
||||
> the original `Host` header **must** be forwarded to Kubo for
|
||||
> [`Gateway.PublicGateways`](config.md#gatewaypublicgateways) to work.
|
||||
> Kubo uses the `Host` header to match configured hostnames and detect
|
||||
> subdomain gateway patterns like `{cid}.ipfs.example.org` or DNSLink hostnames.
|
||||
>
|
||||
> If the `Host` header is not forwarded correctly, Kubo will not recognize
|
||||
> the configured gateway hostnames and requests may be handled incorrectly.
|
||||
>
|
||||
> If `X-Forwarded-Proto` is not set, redirects over HTTPS will use wrong protocol
|
||||
> and DNSLink names will not be inlined for subdomain gateways.
|
||||
>
|
||||
> Example: minimal nginx configuration for `example.org`
|
||||
>
|
||||
> ```nginx
|
||||
> server {
|
||||
> listen 80;
|
||||
> listen [::]:80;
|
||||
>
|
||||
> # IMPORTANT: Include wildcard to match subdomain gateway requests.
|
||||
> # The dot prefix matches both apex domain and all subdomains.
|
||||
> server_name .example.org;
|
||||
>
|
||||
> location / {
|
||||
> proxy_pass http://127.0.0.1:8080;
|
||||
>
|
||||
> # IMPORTANT: Forward the original Host header to Kubo.
|
||||
> # Without this, PublicGateways configuration will not work.
|
||||
> proxy_set_header Host $host;
|
||||
>
|
||||
> # IMPORTANT: X-Forwarded-Proto is required for correct behavior:
|
||||
> # - Redirects will use https:// URLs when set to "https"
|
||||
> # - DNSLink names will be inlined for subdomain gateways
|
||||
> # (e.g., /ipns/en.wikipedia-on-ipfs.org → en-wikipedia--on--ipfs-org.ipns.example.org)
|
||||
> proxy_set_header X-Forwarded-Proto $scheme;
|
||||
> proxy_set_header X-Forwarded-Host $host;
|
||||
> }
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> Common mistakes to avoid:
|
||||
>
|
||||
> - **Missing wildcard in `server_name`:** Using only `server_name example.org;`
|
||||
> will not match subdomain requests like `{cid}.ipfs.example.org`. Always
|
||||
> include `*.example.org` or use the dot prefix `.example.org`.
|
||||
>
|
||||
> - **Wrong `Host` header value:** Using `proxy_set_header Host $proxy_host;`
|
||||
> sends the backend's hostname (e.g., `127.0.0.1:8080`) instead of the
|
||||
> original `Host` header. Always use `$host` or `$http_host`.
|
||||
>
|
||||
> - **Missing `Host` header entirely:** If `proxy_set_header Host` is not
|
||||
> specified, nginx defaults to `$proxy_host`, which breaks gateway routing.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Timeouts:** Configure [`Gateway.RetrievalTimeout`](config.md#gatewayretrievaltimeout)
|
||||
> based on your expected content retrieval times.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Rate Limiting:** Use [`Gateway.MaxConcurrentRequests`](config.md#gatewaymaxconcurrentrequests)
|
||||
> to protect against traffic spikes.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **CDN/Cloudflare:** If using Cloudflare or other CDNs with
|
||||
> [deserialized responses](config.md#gatewaydeserializedresponses) enabled, review
|
||||
> [`Gateway.MaxRangeRequestFileSize`](config.md#gatewaymaxrangerequestfilesize) to avoid
|
||||
> excess bandwidth billing from range request bugs. Cloudflare users may need additional
|
||||
> protection via [Cloudflare Snippets](https://github.com/ipfs/boxo/issues/856#issuecomment-3523944976).
|
||||
|
||||
## Directories
|
||||
|
||||
For convenience, the gateway (mostly) acts like a normal web-server when serving
|
||||
@ -53,7 +134,7 @@ a directory:
|
||||
2. Dynamically build and serve a listing of the contents of the directory.
|
||||
|
||||
<sub><sup>†</sup>This redirect is skipped if the query string contains a
|
||||
`go-get=1` parameter. See [PR#3964](https://github.com/ipfs/kubo/pull/3963)
|
||||
`go-get=1` parameter. See [PR#3963](https://github.com/ipfs/kubo/pull/3963)
|
||||
for details</sub>
|
||||
|
||||
## Static Websites
|
||||
@ -107,10 +188,12 @@ This is equivalent of `ipfs block get`.
|
||||
|
||||
### `application/vnd.ipld.car`
|
||||
|
||||
Returns a [CAR](https://ipld.io/specs/transport/car/) stream for specific DAG and selector.
|
||||
Returns a [CAR](https://ipld.io/specs/transport/car/) stream for a DAG or a subset of it.
|
||||
|
||||
Right now only 'full DAG' implicit selector is implemented.
|
||||
Support for user-provided IPLD selectors is tracked in https://github.com/ipfs/kubo/issues/8769.
|
||||
The `dag-scope` parameter controls which blocks are included: `all` (default, entire DAG),
|
||||
`entity` (logical unit like a file), or `block` (single block). For [UnixFS](https://specs.ipfs.tech/unixfs/) files,
|
||||
`entity-bytes` enables byte range requests. See [IPIP-402](https://specs.ipfs.tech/ipips/ipip-0402/)
|
||||
for details.
|
||||
|
||||
This is a rough equivalent of `ipfs dag export`.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user