docs: clarify Gateway.PublicGateways (#10525)
* docs: clarify Gateway.PublicGateways * docs: caution about reusing domains
Marcin Rataj committed
Sep 26, 2024 at 19:31 UTC
836d51650dac34a2b1f6447c3f195fbc5e9920bf
1 file changed
+24
-5
docs/config.md
+24
-5
@@ -682,7 +682,18 @@ We are working on developing a modern replacement. To support our efforts, pleas
682
683
### `Gateway.PublicGateways`
684
685
-`PublicGateways` is a dictionary for defining gateway behavior on specified hostnames.
685
+> [!IMPORTANT]
686
+> This configuration is **NOT** for HTTP Client, it is for HTTP Server – use this ONLY if you want to run your own IPFS gateway.
687
+
688
+`PublicGateways` is a configuration map used for dictionary for customizing gateway behavior
689
+on specified hostnames that point at your Kubo instance.
690
+
691
+It is useful when you want to run [Path gateway](https://specs.ipfs.tech/http-gateways/path-gateway/) on `example.com/ipfs/cid`,
692
+and [Subdomain gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/) on `cid.ipfs.example.org`,
693
+or limit `verifiable.example.net` to response types defined in [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) specification.
694
+
695
+> [!CAUTION]
696
+> Keys (Hostnames) MUST be unique. Do not use the same parent domain for multiple gateway types, it will break origin isolation.
697
698
Hostnames can optionally be defined with one or more wildcards.
699
@@ -715,7 +726,9 @@ Type: `array[string]`
726
727
#### `Gateway.PublicGateways: UseSubdomains`
728
718
-A boolean to configure whether the gateway at the hostname provides [Origin isolation](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
729
+A boolean to configure whether the gateway at the hostname should be
730
+a [Subdomain Gateway](https://specs.ipfs.tech/http-gateways/subdomain-gateway/)
731
+and provide [Origin isolation](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
732
between content roots.
733
734
- `true` - enables [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://*.{hostname}/`
@@ -764,7 +777,7 @@ Type: `bool`
777
778
An optional flag to explicitly configure whether subdomain gateway's redirects
779
(enabled by `UseSubdomains: true`) should always inline a DNSLink name (FQDN)
767
-into a single DNS label:
780
+into a single DNS label ([specification](https://specs.ipfs.tech/http-gateways/subdomain-gateway/#host-request-header)):
781
782
```
783
//example.com/ipns/example.net → HTTP 301 → //example-net.ipns.example.com
@@ -783,8 +796,14 @@ Type: `flag`
796
#### `Gateway.PublicGateways: DeserializedResponses`
797
798
An optional flag to explicitly configure whether this gateway responds to deserialized
786
-requests, or not. By default, it is enabled. When disabling this option, the gateway
787
-operates as a Trustless Gateway only: https://specs.ipfs.tech/http-gateways/trustless-gateway/.
799
+requests, or not. By default, it is enabled.
800
+
801
+When disabled, the gateway operates strictly as a [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
802
+
803
+> [!TIP]
804
+> Disabling deserialized responses will protect you from acting as a free web hosting,
805
+> while still allowing trustless clients like [@helia/verified-fetch](https://www.npmjs.com/package/@helia/verified-fetch)
806
+> to utilize it for [trustless, verifiable data retrieval](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval).
807
808
Default: same as global `Gateway.DeserializedResponses`
809