From 2dcba6b026095258c5d7011fd9af4cff5fb2ebdb Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 29 May 2026 15:33:44 +0200
Subject: [PATCH 1/6] docs: guide to replace public gateways with self-hosted
 IPFS

New how-to for non-browser clients and web apps still calling ipfs.io
or dweb.link, routing each case to a drop-in replacement:

- backend retrieve-only -> Rainbow, with trustless-only config for
  public hostnames
- backend retrieve and publish -> Kubo, plus pinning services or
  IPFS Cluster for redundancy
- browser JS -> @helia/verified-fetch, with self-hosted Someguy and
  Rainbow/Kubo to stay independent of public utilities

Linked from the IPFS Gateway sidebar group and the how-to index.
---
 docs/.vuepress/config.js                      |   1 +
 docs/how-to/README.md                         |   1 +
 ...e-public-gateways-with-self-hosted-ipfs.md | 232 ++++++++++++++++++
 3 files changed, 234 insertions(+)
 create mode 100644 docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 775624d62..b38a112ff 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -292,6 +292,7 @@ module.exports = {
               sidebarDepth: 1,
               collapsable: true,
               children: [
+                '/how-to/replace-public-gateways-with-self-hosted-ipfs',
                 '/how-to/gateway-best-practices',
                 '/how-to/troubleshooting',
               ]
diff --git a/docs/how-to/README.md b/docs/how-to/README.md
index 061eaa225..55c9490d8 100644
--- a/docs/how-to/README.md
+++ b/docs/how-to/README.md
@@ -7,6 +7,7 @@ description: Hands-on guides to using and developing with IPFS to build decentra
 
 See the site navigation menu for all our how-tos, organized by topic area, including favorites like these:
 
+- **Move off public gateways** by [replacing `ipfs.io` and `dweb.link` with self-hosted IPFS](replace-public-gateways-with-self-hosted-ipfs.md)
 - **Customize your install** by [configuring a node](configure-node.md), modifying the [bootstrap list](modify-bootstrap-list.md), and more
 - **Learn how to manage files** in IPFS with tutorials on concepts like [pinning](pin-files.md), how to [work with blocks](work-with-blocks.md), learning how to [content address data sets](content-addressing-data-sets.md).
 - **Publish scientific data** by exploring the [scientific data and IPFS landscape guide](scientific-data/landscape-guide.md) or learning how to [publish geospatial Zarr data with IPFS](scientific-data/publish-geospatial-zarr-data.md)
diff --git a/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
new file mode 100644
index 000000000..d77b453f1
--- /dev/null
+++ b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
@@ -0,0 +1,232 @@
+---
+title: Replace public gateways with self-hosted IPFS
+description: Replace ipfs.io and dweb.link calls with your own IPFS infrastructure.
+---
+
+# Replace public gateways with self-hosted IPFS
+
+If your app fetches content from `ipfs.io` or `dweb.link`, this guide shows you how to switch to infrastructure you control.
+
+When you are done, your app fetches the same content by CID from a gateway you run, with no dependency on `ipfs.io` or `dweb.link`.
+
+## Why this guide
+
+The public gateways at `ipfs.io` and `dweb.link` are not the right place to send production traffic. They are a shared [public good (best-effort)](../concepts/public-utilities.md) with no SLA and no performance knobs you control. Running your own infrastructure puts you in charge of both: you set the SLA your users get, and you tune for the performance your app needs. Read [A post-gateway world](https://ipshipyard.com/blog/2025-a-post-gateway-world/) and [IPFS gateways: redirect to in-browser](https://ipshipyard.com/blog/2026-ipfs-gateways-redirect-inbrowser-link/) for the background.
+
+This guide covers two audiences: code in a browser page that fetches from `ipfs.io` via the Fetch API, a Service Worker, or hotlinked subresources (`<img>`, `<script>`, CSS `url()`); and non-browser clients (server code, scripts, mobile apps, CLI tools). Top-level browser navigations (the address bar case) are out of scope; the in-browser redirect linked above handles those without code changes.
+
+For background on the shared infrastructure you are moving away from, see [Public utilities](../concepts/public-utilities.md).
+
+## Pick your path
+
+Two things you might do with IPFS:
+
+- **Retrieve** (the "read" side): fetch existing content by CID. This is what a public gateway does for you today.
+- **Publish and host** (the "write" side): add new content and keep it online so other peers can fetch it.
+
+Match your setup to one of the three rows, then jump to that section.
+
+| Where you use IPFS                       | What you do with it                                                            | Jump to                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Browser (web page)                       | Retrieve via the Fetch API, a Service Worker, or as a subresource (`<img>`, `<script>`) | [Set up `@helia/verified-fetch` ↓](#browser-apps)            |
+| Backend (server, script, CLI, mobile)    | Retrieve only (`curl`, Node.js, Go, Python, etc.)                              | [Set up Rainbow ↓](#backend-retrieve-only-rainbow)                   |
+| Backend (server, script, CLI, mobile)    | Retrieve and publish (host data)                                               | [Set up Kubo ↓](#backend-retrieve-and-publish-kubo)                  |
+
+Every path ends with the same drop-in change: swap the `ipfs.io` or `dweb.link` URL for your own.
+
+**Use path-style URLs for non-browser clients.** Point at the path-style local gateway: `http://127.0.0.1:{port}/ipfs/{CID}/path/to/file`. Subdomain URLs like `{CID}.ipfs.{host}` only add value for top-level browser navigation, where the browser uses the subdomain to give each site its own origin. If your old code already uses subdomain URLs from `dweb.link`, switch to path-style against your local gateway. The examples below do that.
+
+**Internal-only backends: think Redis, not CDN.** If your backend uses IPFS the way it would use Redis (fetch JSON or a blob by CID, then act on it; nothing reaches end users directly), deploy Rainbow or Kubo on the same host as your app and call it over localhost. The URL swap above is the whole setup. The "Put it on your own domain" and "Trustless vs deserialized" subsections in each backend section below only apply when you also expose the gateway to clients outside your own infrastructure.
+
+## Backend, retrieve only: Rainbow
+
+[Rainbow](https://github.com/ipfs/rainbow#readme) is a small binary that runs a trustless HTTP gateway on your machine. It retrieves and verifies content; it does not publish or host data of its own. Use it when your backend only fetches from IPFS.
+
+### Run it
+
+Follow the install steps in the [Rainbow README](https://github.com/ipfs/rainbow#readme). Once running, Rainbow serves a gateway on `http://127.0.0.1:8090` by default.
+
+### Swap your URLs
+
+Your code fetches from a URL like one of these today:
+
+```
+https://ipfs.io/ipfs/{CID}/path/to/file
+https://{CID}.ipfs.dweb.link/path/to/file
+```
+
+Point it at your local gateway instead:
+
+```
+http://127.0.0.1:8090/ipfs/{CID}/path/to/file
+```
+
+Confirm it works by requesting a CID your app already uses; a `200` with the same bytes you got from `ipfs.io` means the swap is done:
+
+```bash
+curl http://127.0.0.1:8090/ipfs/{CID}
+```
+
+### Put it on your own domain
+
+For HTTPS under a hostname you control, run Rainbow behind Caddy. The Caddy setup in [Secure Kubo RPC with TLS and HTTP Auth](./kubo-rpc-tls-auth.md) works the same way for Rainbow. Point the reverse proxy at `127.0.0.1:8090` instead of the Kubo RPC port.
+
+### Trustless vs deserialized responses
+
+Skip this subsection if Rainbow only serves traffic from your own backend on localhost; deserialized responses are safe there because you trust the node. The rules below apply when you put the gateway on a public hostname.
+
+A gateway can answer in two modes:
+
+- **Deserialized**: the gateway returns the final file, HTML, or JSON. Convenient, but the client has to trust that the gateway returned the correct bytes for the CID. Fine on your own backend, where you trust the node.
+- **Trustless**: the gateway returns raw blocks or CAR streams, selected with `?format=raw`, `?format=car`, or a matching `Accept` header. The client cryptographically checks the response against the requested CID, so a tampering gateway is detectable. See the [trustless gateway spec](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
+
+On a public HTTPS domain, serve trustless responses only. Keep the deserialized mode for your own internal callers. Rainbow reads this from environment variables, so set them before launching it (export them in your shell, put them in your `.env`, or add `Environment=` lines to your systemd unit):
+
+```bash
+# Public-facing domain: serve only verifiable formats
+RAINBOW_TRUSTLESS_GATEWAY_DOMAINS=rainbow-gateway.example.net
+
+# Keep deserialized path gateway on localhost for internal use
+RAINBOW_GATEWAY_DOMAINS=127.0.0.1
+
+# Keep deserialized subdomain gateway on localhost
+RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS=localhost
+```
+
+If the same domain appears in both `RAINBOW_TRUSTLESS_GATEWAY_DOMAINS` and `RAINBOW_GATEWAY_DOMAINS`, the trustless setting wins, so it is safe to list the public hostname in both. See [Rainbow environment variables](https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md) for the full list.
+
+## Backend, retrieve and publish: Kubo
+
+If you publish and host content as well as retrieve it, run [Kubo](../install/command-line.md). It is the reference IPFS node and gives you both gateway retrieval and publishing APIs.
+
+### Run it
+
+Follow [Install Kubo](../install/command-line.md). Once started, Kubo serves a gateway on `http://127.0.0.1:8080` and an RPC API on `http://127.0.0.1:5001`.
+
+### Swap your URLs
+
+Your code fetches from a URL like one of these today:
+
+```
+https://ipfs.io/ipfs/{CID}/path/to/file
+https://{CID}.ipfs.dweb.link/path/to/file
+```
+
+Point it at your local gateway instead:
+
+```
+http://127.0.0.1:8080/ipfs/{CID}/path/to/file
+```
+
+Confirm it works by requesting a CID your app already uses:
+
+```bash
+curl http://127.0.0.1:8080/ipfs/{CID}
+```
+
+### Publish and host content
+
+Once Kubo is running on your server, it hosts every CID you add while the daemon runs and the data stays pinned. Use `ipfs add` from the [command-line quick start](./command-line-quick-start.md), or call the [Kubo RPC API](../reference/kubo/rpc.md) from your backend.
+
+### Add redundancy
+
+You have two options for keeping content available if a single node goes down:
+
+- **Use a pinning service.** A third party stores extra copies for you. See [Work with pinning services](./work-with-pinning-services.md).
+- **Run IPFS Cluster.** A small cluster of your own nodes shares pinsets across the group. See [Server infrastructure](../install/server-infrastructure.md).
+
+### Put it on your own domain
+
+For HTTPS and authenticated RPC on a domain you control, follow [Secure Kubo RPC with TLS and HTTP Auth](./kubo-rpc-tls-auth.md). It walks through Caddy with automatic TLS.
+
+The [trustless-only rule from the Rainbow section](#trustless-vs-deserialized-responses) applies to Kubo too. When the gateway hostname is public, set `DeserializedResponses` to `false` so the public endpoint serves only verifiable formats:
+
+```bash
+ipfs config --json Gateway.PublicGateways '{"kubo-gateway.example.net": {"Paths": ["/ipfs", "/ipns"], "DeserializedResponses": false}}'
+```
+
+See [Gateway recipes](https://github.com/ipfs/kubo/blob/master/docs/config.md#gateway) in the Kubo config docs for more options.
+
+## Browser apps
+
+If you fetch IPFS content from JavaScript in a web page, switch to [`@helia/verified-fetch`](https://www.npmjs.com/package/@helia/verified-fetch). It is a drop-in replacement for `fetch` that retrieves content in the browser itself.
+
+### Install
+
+```bash
+npm install @helia/verified-fetch
+```
+
+### Swap your fetches
+
+```js
+// Before
+const res = await fetch('https://ipfs.io/ipfs/bafy.../path/to/file')
+
+// After
+import { verifiedFetch } from '@helia/verified-fetch'
+const res = await verifiedFetch('ipfs://bafy.../path/to/file')
+```
+
+You can also pass plain HTTP-style URLs like `verifiedFetch('https://bafy....ipfs.example.com/path/to/file')` if you already use subdomain URLs. See the [`@helia/verified-fetch` README](https://www.npmjs.com/package/@helia/verified-fetch) for the full API.
+
+To confirm the swap, load your page and open the browser network panel: requests to the content no longer go to `ipfs.io` or `dweb.link`.
+
+### How it works, and what you still depend on
+
+The main win: `verified-fetch` retrieves content directly from peers, in the browser, over libp2p (the peer-to-peer networking stack IPFS uses). Shared HTTP gateways drop out of the data path.
+
+Two pieces still use HTTP, and they default to public endpoints:
+
+- **Routing** finds which peers have a given CID. Default: `https://delegated-ipfs.dev` ([HTTP delegated routing v1](https://specs.ipfs.tech/routing/http-routing-v1/)).
+- **Trustless gateway fallback** kicks in only when peer-to-peer retrieval fails in the browser. Default: `https://trustless-gateway.link`. Pass `gateways: []` to disable it.
+
+For production, point both at your own infrastructure: run [Someguy](#run-someguy) for `/routing/v1`, and [Rainbow](#backend-retrieve-only-rainbow) or [Kubo](#backend-retrieve-and-publish-kubo) for the trustless gateway. The next section shows the configuration.
+
+## Stay independent of public utilities
+
+Run [Someguy](https://github.com/ipfs/someguy#readme) as your `/routing/v1` endpoint, run [Rainbow](#backend-retrieve-only-rainbow) or [Kubo](#backend-retrieve-and-publish-kubo) as your trustless gateway, and point your clients at both. You really want to swap the public good (best-effort) HTTP endpoints that `@helia/verified-fetch` uses out of the box.
+
+### Run Someguy
+
+Follow the [Someguy README](https://github.com/ipfs/someguy#readme). It exposes a `/routing/v1` HTTP endpoint that answers "who has this CID" for your clients.
+
+### Point `@helia/verified-fetch` at your own infrastructure
+
+Combine your Someguy for routing with your Rainbow or Kubo for retrieval. Use HTTPS endpoints under your own domains; browsers block plain HTTP requests from HTTPS pages, and the [Caddy setup](./kubo-rpc-tls-auth.md) handles TLS for you:
+
+```js
+import { createVerifiedFetch } from '@helia/verified-fetch'
+
+const verifiedFetch = await createVerifiedFetch({
+  gateways: ['https://rainbow-gateway.example.net'],
+  routers: ['https://someguy-routing.example.net']
+})
+
+const res = await verifiedFetch('ipfs://bafy.../path/to/file')
+```
+
+Replace the example domains with your own. See the [`@helia/verified-fetch` README](https://www.npmjs.com/package/@helia/verified-fetch) for the current option names.
+
+### Point your own Kubo or Rainbow at Someguy (optional)
+
+Since Someguy caches routing answers, you can also point your backend Kubo or Rainbow node at it. By default both reach out to public delegated routing endpoints; this override sends them through your Someguy instead. Skip this step if you do not run a backend node.
+
+For Kubo, override the delegated routers and restart the daemon:
+
+```bash
+ipfs config --json Routing.DelegatedRouters '["https://someguy-routing.example.net/routing/v1"]'
+```
+
+For Rainbow, set the env var before startup:
+
+```bash
+RAINBOW_HTTP_ROUTERS=https://someguy-routing.example.net/routing/v1
+```
+
+## Further reading
+
+- [Service Worker Gateway](https://github.com/ipfs/service-worker-gateway#readme): worked end-to-end example built on `@helia/verified-fetch`. Useful if you want a single web entry point that handles all IPFS URLs in your app.
+- [Best practices for HTTP Gateways](./gateway-best-practices.md): caching, CORS, and reverse-proxy guidance once you run your own gateway.
+- [Secure Kubo RPC with TLS and HTTP Auth](./kubo-rpc-tls-auth.md): Caddy with automatic TLS on your own domain.
+- [Public utilities](../concepts/public-utilities.md): what the shared IPFS infrastructure is, and what depends on it.

From fa52e87f6c8a275bb4ddc8c966a97d3b116894a4 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 29 May 2026 16:08:03 +0200
Subject: [PATCH 2/6] docs: cross-link and refine self-hosted gateway guide

Point readers from the gateway and public-utility docs to the
migration guide, and reorder it to match how readers choose a path.

- guide: lead with @helia/verified-fetch, then Rainbow, then Kubo,
  matching the "Pick your path" table order
- link the guide from public-utilities, ipfs-gateway, ipfs-in-web-apps,
  address-ipfs-on-web, and gateway-best-practices
- note verified-fetch can deserialize a trustless response client-side,
  so apps needing files still work against a trustless-only endpoint
- note RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS needs localhost or a Public
  Suffix List hostname for browser origin isolation
- sidebar: place the guide before troubleshooting
---
 docs/.vuepress/config.js                      |   2 +-
 docs/concepts/ipfs-gateway.md                 |   2 +
 docs/concepts/public-utilities.md             |   2 +
 docs/how-to/address-ipfs-on-web.md            |   2 +-
 docs/how-to/gateway-best-practices.md         |   2 +
 docs/how-to/ipfs-in-web-apps.md               |   2 +-
 ...e-public-gateways-with-self-hosted-ipfs.md | 164 +++++++++---------
 7 files changed, 92 insertions(+), 84 deletions(-)

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index b38a112ff..9d46ffb3a 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -292,8 +292,8 @@ module.exports = {
               sidebarDepth: 1,
               collapsable: true,
               children: [
-                '/how-to/replace-public-gateways-with-self-hosted-ipfs',
                 '/how-to/gateway-best-practices',
+                '/how-to/replace-public-gateways-with-self-hosted-ipfs',
                 '/how-to/troubleshooting',
               ]
             },
diff --git a/docs/concepts/ipfs-gateway.md b/docs/concepts/ipfs-gateway.md
index f79c0b5cf..704e91ae9 100644
--- a/docs/concepts/ipfs-gateway.md
+++ b/docs/concepts/ipfs-gateway.md
@@ -43,6 +43,8 @@ Public ([recursive](#recursive-vs-non-recursive-gateways)) gateways are provided
 
 For a list of public gateways, see the [IPFS Gateways Checker](https://ipfs.fyi/gateways).
 
+If your app already calls a public gateway and you want to run your own instead, see [Replace public gateways with self-hosted IPFS](../how-to/replace-public-gateways-with-self-hosted-ipfs.md).
+
 ## Gateway types
 
 There are multiple gateway types, each with specific use case, security, performance, and functional implications.
diff --git a/docs/concepts/public-utilities.md b/docs/concepts/public-utilities.md
index 0e4a5e110..625d726a2 100644
--- a/docs/concepts/public-utilities.md
+++ b/docs/concepts/public-utilities.md
@@ -12,6 +12,8 @@ These include [IPFS Gateways](./ipfs-gateway.md), hosted [Delegated Routing V1 e
 
 These utilities make it easier to retrieve data from the IPFS network in resource-constrained environments such as browsers and low-powered devices.
 
+They are a great way to get started. When your app outgrows best-effort traffic and you want infrastructure you control, see [Replace public gateways with self-hosted IPFS](../how-to/replace-public-gateways-with-self-hosted-ipfs.md).
+
 ## Public IPFS Gateways
 
 The IPFS Foundation provides the following public gateways:
diff --git a/docs/how-to/address-ipfs-on-web.md b/docs/how-to/address-ipfs-on-web.md
index 698f8b3a2..97b0ca8ed 100644
--- a/docs/how-to/address-ipfs-on-web.md
+++ b/docs/how-to/address-ipfs-on-web.md
@@ -20,7 +20,7 @@ For example:
 https://ipfs.io/ipfs/bafybeihkoviema7g3gxyt6la7vd5ho32ictqbilu3wnlo3rs7ewhnp7lly
 ```
 
-A [self-hosted local gateway](https://docs.ipfs.tech/install/) can also be used, instead of `ipfs.io`. 
+A [self-hosted local gateway](https://docs.ipfs.tech/install/) can also be used, instead of `ipfs.io`. To move an existing app off the public gateways, see [Replace public gateways with self-hosted IPFS](./replace-public-gateways-with-self-hosted-ipfs.md).
 
 ## IPFS addressing in brief
 
diff --git a/docs/how-to/gateway-best-practices.md b/docs/how-to/gateway-best-practices.md
index a1dd324bf..76b22dbfe 100644
--- a/docs/how-to/gateway-best-practices.md
+++ b/docs/how-to/gateway-best-practices.md
@@ -23,6 +23,8 @@ Any form of gateway provides a bridge for apps without native support of IPFS. B
 
 If you are running an IPFS node that is also configured as an IPFS gateway, each of the tips below can help improve the discovery and retrievability of your CIDs.
 
+If you are moving off the public `ipfs.io` or `dweb.link` gateways, see [Replace public gateways with self-hosted IPFS](./replace-public-gateways-with-self-hosted-ipfs.md) for a drop-in migration path.
+
 - Pin your CIDs to multiple IPFS nodes to ensure reliable availability and resilience to failures of nodes and network partitions. To make pinning easier, use the vendor-agnostic [Pinning Service OpenAPI Specification](https://ipfs.github.io/pinning-services-api-spec/) that is already [supported by many IPFS node implementations, client libraries, and existing pinning services](https://github.com/ipfs/pinning-services-api-spec#adoption).
 - Use a custom domain that you control as your IPFS gateway for flexibility in implementing performance optimizations. You can do this using one of the following methods:
   - Point a domain you control like `mydomain.ipfs.yourdomain.io` to a reverse proxy like nginx, which will proxy requests to a public gateway, allowing you to switch public gateways if there's downtime.
diff --git a/docs/how-to/ipfs-in-web-apps.md b/docs/how-to/ipfs-in-web-apps.md
index 626657954..07da76f13 100644
--- a/docs/how-to/ipfs-in-web-apps.md
+++ b/docs/how-to/ipfs-in-web-apps.md
@@ -68,7 +68,7 @@ From a high level, there are several ways to retrieve data with IPFS in web appl
 
 - Using the [Verified Fetch](https://www.npmjs.com/package/@helia/verified-fetch) library, which was modelled after the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and returns [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects, with the main difference being that it allows you to fetch data by CID, abstracting away the details of content routing, transports and retrieval. For more examples and background see the [release blog post](https://blog.ipfs.tech/verified-fetch/).
 - Using the [Helia](https://github.com/ipfs/helia/) library, which is the foundation for the `@helia/verified-fetch` library, and provides a more comprehensive and modular API for interacting with the IPFS network, beyond just retrieval.
-- Using public recursive gateways, e.g. `ipfs.io` with HTTP. This is not recommended for most use cases, because it forgoes the verifiability and trustlessness enabled by content addressing. Granted, it might be the easiest way to retrieve data in a web application, but is also the most fraught with security and centralization concerns.
+- Using public recursive gateways, e.g. `ipfs.io` with HTTP. This is not recommended for most use cases, because it forgoes the verifiability and trustlessness enabled by content addressing. Granted, it might be the easiest way to retrieve data in a web application, but is also the most fraught with security and centralization concerns. If your app already fetches from `ipfs.io` or `dweb.link` this way, see [Replace public gateways with self-hosted IPFS](./replace-public-gateways-with-self-hosted-ipfs.md) for a drop-in move to `@helia/verified-fetch`.
 
 ### Example: Image retrieval with Verified Fetch
 
diff --git a/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
index d77b453f1..4e8bbd75e 100644
--- a/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
+++ b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
@@ -11,7 +11,7 @@ When you are done, your app fetches the same content by CID from a gateway you r
 
 ## Why this guide
 
-The public gateways at `ipfs.io` and `dweb.link` are not the right place to send production traffic. They are a shared [public good (best-effort)](../concepts/public-utilities.md) with no SLA and no performance knobs you control. Running your own infrastructure puts you in charge of both: you set the SLA your users get, and you tune for the performance your app needs. Read [A post-gateway world](https://ipshipyard.com/blog/2025-a-post-gateway-world/) and [IPFS gateways: redirect to in-browser](https://ipshipyard.com/blog/2026-ipfs-gateways-redirect-inbrowser-link/) for the background.
+The public gateways at `ipfs.io` and `dweb.link` are a great way to get started, and plenty of apps lean on them early on. They are a shared [public good (best-effort)](../concepts/public-utilities.md), though, with no SLA and no performance knobs you control, so they are not built for production traffic. Running your own infrastructure puts you in charge of both: you set the SLA your users get, and you tune for the performance your app needs. Read [A post-gateway world](https://ipshipyard.com/blog/2025-a-post-gateway-world/) and [IPFS gateways: redirect to in-browser](https://ipshipyard.com/blog/2026-ipfs-gateways-redirect-inbrowser-link/) for the background.
 
 This guide covers two audiences: code in a browser page that fetches from `ipfs.io` via the Fetch API, a Service Worker, or hotlinked subresources (`<img>`, `<script>`, CSS `url()`); and non-browser clients (server code, scripts, mobile apps, CLI tools). Top-level browser navigations (the address bar case) are out of scope; the in-browser redirect linked above handles those without code changes.
 
@@ -38,6 +38,83 @@ Every path ends with the same drop-in change: swap the `ipfs.io` or `dweb.link`
 
 **Internal-only backends: think Redis, not CDN.** If your backend uses IPFS the way it would use Redis (fetch JSON or a blob by CID, then act on it; nothing reaches end users directly), deploy Rainbow or Kubo on the same host as your app and call it over localhost. The URL swap above is the whole setup. The "Put it on your own domain" and "Trustless vs deserialized" subsections in each backend section below only apply when you also expose the gateway to clients outside your own infrastructure.
 
+## Browser apps
+
+If you fetch IPFS content from JavaScript in a web page, switch to [`@helia/verified-fetch`](https://www.npmjs.com/package/@helia/verified-fetch). It is a drop-in replacement for `fetch` that retrieves content in the browser itself.
+
+### Install
+
+```bash
+npm install @helia/verified-fetch
+```
+
+### Swap your fetches
+
+```js
+// Before
+const res = await fetch('https://ipfs.io/ipfs/bafy.../path/to/file')
+
+// After
+import { verifiedFetch } from '@helia/verified-fetch'
+const res = await verifiedFetch('ipfs://bafy.../path/to/file')
+```
+
+You can also pass plain HTTP-style URLs like `verifiedFetch('https://bafy....ipfs.example.com/path/to/file')` if you already use subdomain URLs. See the [`@helia/verified-fetch` README](https://www.npmjs.com/package/@helia/verified-fetch) for the full API.
+
+To confirm the swap, load your page and open the browser network panel: requests to the content no longer go to `ipfs.io` or `dweb.link`.
+
+### How it works, and what you still depend on
+
+The main win: `verified-fetch` retrieves content directly from peers, in the browser, over libp2p (the peer-to-peer networking stack IPFS uses). Shared HTTP gateways drop out of the data path.
+
+Two pieces still use HTTP, and they default to public endpoints:
+
+- **Routing** finds which peers have a given CID. Default: `https://delegated-ipfs.dev` ([HTTP delegated routing v1](https://specs.ipfs.tech/routing/http-routing-v1/)).
+- **Trustless gateway fallback** kicks in only when peer-to-peer retrieval fails in the browser. Default: `https://trustless-gateway.link`. Pass `gateways: []` to disable it.
+
+For production, point both at your own infrastructure: run [Someguy](#run-someguy) for `/routing/v1`, and [Rainbow](#backend-retrieve-only-rainbow) or [Kubo](#backend-retrieve-and-publish-kubo) for the trustless gateway. The next section shows the configuration.
+
+## Stay independent of public utilities
+
+Run [Someguy](https://github.com/ipfs/someguy#readme) as your `/routing/v1` endpoint, run [Rainbow](#backend-retrieve-only-rainbow) or [Kubo](#backend-retrieve-and-publish-kubo) as your trustless gateway, and point your clients at both. This swaps out the best-effort public endpoints that `@helia/verified-fetch` uses out of the box, so your routing and fallback stay on infrastructure you control too.
+
+### Run Someguy
+
+Follow the [Someguy README](https://github.com/ipfs/someguy#readme). It exposes a `/routing/v1` HTTP endpoint that answers "who has this CID" for your clients.
+
+### Point `@helia/verified-fetch` at your own infrastructure
+
+Combine your Someguy for routing with your Rainbow or Kubo for retrieval. Use HTTPS endpoints under your own domains; browsers block plain HTTP requests from HTTPS pages, and the [Caddy setup](./kubo-rpc-tls-auth.md) handles TLS for you:
+
+```js
+import { createVerifiedFetch } from '@helia/verified-fetch'
+
+const verifiedFetch = await createVerifiedFetch({
+  gateways: ['https://rainbow-gateway.example.net'],
+  routers: ['https://someguy-routing.example.net']
+})
+
+const res = await verifiedFetch('ipfs://bafy.../path/to/file')
+```
+
+Replace the example domains with your own. See the [`@helia/verified-fetch` README](https://www.npmjs.com/package/@helia/verified-fetch) for the current option names.
+
+### Point your own Kubo or Rainbow at Someguy (optional)
+
+Since Someguy caches routing answers, you can also point your backend Kubo or Rainbow node at it. By default both reach out to public delegated routing endpoints; this override sends them through your Someguy instead. Skip this step if you do not run a backend node.
+
+For Kubo, override the delegated routers and restart the daemon:
+
+```bash
+ipfs config --json Routing.DelegatedRouters '["https://someguy-routing.example.net/routing/v1"]'
+```
+
+For Rainbow, set the env var before startup:
+
+```bash
+RAINBOW_HTTP_ROUTERS=https://someguy-routing.example.net/routing/v1
+```
+
 ## Backend, retrieve only: Rainbow
 
 [Rainbow](https://github.com/ipfs/rainbow#readme) is a small binary that runs a trustless HTTP gateway on your machine. It retrieves and verifies content; it does not publish or host data of its own. Use it when your backend only fetches from IPFS.
@@ -80,21 +157,23 @@ A gateway can answer in two modes:
 - **Deserialized**: the gateway returns the final file, HTML, or JSON. Convenient, but the client has to trust that the gateway returned the correct bytes for the CID. Fine on your own backend, where you trust the node.
 - **Trustless**: the gateway returns raw blocks or CAR streams, selected with `?format=raw`, `?format=car`, or a matching `Accept` header. The client cryptographically checks the response against the requested CID, so a tampering gateway is detectable. See the [trustless gateway spec](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
 
-On a public HTTPS domain, serve trustless responses only. Keep the deserialized mode for your own internal callers. Rainbow reads this from environment variables, so set them before launching it (export them in your shell, put them in your `.env`, or add `Environment=` lines to your systemd unit):
+On a public HTTPS domain, serve trustless responses only. Keep the deserialized mode for your own internal callers. If your web or mobile app needs the final file, HTML, or JSON rather than raw blocks, it can still get that from a trustless endpoint: [`@helia/verified-fetch`](#browser-apps) fetches the trustless response and deserializes it on the client after verifying it against the CID, so you get deserialized data without trusting the gateway. Rainbow reads this from environment variables, so set them before launching it (export them in your shell, put them in your `.env`, or add `Environment=` lines to your systemd unit):
 
 ```bash
 # Public-facing domain: serve only verifiable formats
 RAINBOW_TRUSTLESS_GATEWAY_DOMAINS=rainbow-gateway.example.net
 
-# Keep deserialized path gateway on localhost for internal use
+# Deserialized path gateway on localhost, for internal backend (non-browser) use
 RAINBOW_GATEWAY_DOMAINS=127.0.0.1
 
-# Keep deserialized subdomain gateway on localhost
+# Deserialized subdomain gateway; use localhost or a Public Suffix List domain (see note below)
 RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS=localhost
 ```
 
 If the same domain appears in both `RAINBOW_TRUSTLESS_GATEWAY_DOMAINS` and `RAINBOW_GATEWAY_DOMAINS`, the trustless setting wins, so it is safe to list the public hostname in both. See [Rainbow environment variables](https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md) for the full list.
 
+Only set `RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS` to `localhost` or to a hostname listed in the [Public Suffix List](https://publicsuffix.org/). Browsers rely on that list to give each `{CID}.ipfs.{host}` subdomain its own origin, so origin isolation only works on a registered suffix.
+
 ## Backend, retrieve and publish: Kubo
 
 If you publish and host content as well as retrieve it, run [Kubo](../install/command-line.md). It is the reference IPFS node and gives you both gateway retrieval and publishing APIs.
@@ -147,83 +226,6 @@ ipfs config --json Gateway.PublicGateways '{"kubo-gateway.example.net": {"Paths"
 
 See [Gateway recipes](https://github.com/ipfs/kubo/blob/master/docs/config.md#gateway) in the Kubo config docs for more options.
 
-## Browser apps
-
-If you fetch IPFS content from JavaScript in a web page, switch to [`@helia/verified-fetch`](https://www.npmjs.com/package/@helia/verified-fetch). It is a drop-in replacement for `fetch` that retrieves content in the browser itself.
-
-### Install
-
-```bash
-npm install @helia/verified-fetch
-```
-
-### Swap your fetches
-
-```js
-// Before
-const res = await fetch('https://ipfs.io/ipfs/bafy.../path/to/file')
-
-// After
-import { verifiedFetch } from '@helia/verified-fetch'
-const res = await verifiedFetch('ipfs://bafy.../path/to/file')
-```
-
-You can also pass plain HTTP-style URLs like `verifiedFetch('https://bafy....ipfs.example.com/path/to/file')` if you already use subdomain URLs. See the [`@helia/verified-fetch` README](https://www.npmjs.com/package/@helia/verified-fetch) for the full API.
-
-To confirm the swap, load your page and open the browser network panel: requests to the content no longer go to `ipfs.io` or `dweb.link`.
-
-### How it works, and what you still depend on
-
-The main win: `verified-fetch` retrieves content directly from peers, in the browser, over libp2p (the peer-to-peer networking stack IPFS uses). Shared HTTP gateways drop out of the data path.
-
-Two pieces still use HTTP, and they default to public endpoints:
-
-- **Routing** finds which peers have a given CID. Default: `https://delegated-ipfs.dev` ([HTTP delegated routing v1](https://specs.ipfs.tech/routing/http-routing-v1/)).
-- **Trustless gateway fallback** kicks in only when peer-to-peer retrieval fails in the browser. Default: `https://trustless-gateway.link`. Pass `gateways: []` to disable it.
-
-For production, point both at your own infrastructure: run [Someguy](#run-someguy) for `/routing/v1`, and [Rainbow](#backend-retrieve-only-rainbow) or [Kubo](#backend-retrieve-and-publish-kubo) for the trustless gateway. The next section shows the configuration.
-
-## Stay independent of public utilities
-
-Run [Someguy](https://github.com/ipfs/someguy#readme) as your `/routing/v1` endpoint, run [Rainbow](#backend-retrieve-only-rainbow) or [Kubo](#backend-retrieve-and-publish-kubo) as your trustless gateway, and point your clients at both. You really want to swap the public good (best-effort) HTTP endpoints that `@helia/verified-fetch` uses out of the box.
-
-### Run Someguy
-
-Follow the [Someguy README](https://github.com/ipfs/someguy#readme). It exposes a `/routing/v1` HTTP endpoint that answers "who has this CID" for your clients.
-
-### Point `@helia/verified-fetch` at your own infrastructure
-
-Combine your Someguy for routing with your Rainbow or Kubo for retrieval. Use HTTPS endpoints under your own domains; browsers block plain HTTP requests from HTTPS pages, and the [Caddy setup](./kubo-rpc-tls-auth.md) handles TLS for you:
-
-```js
-import { createVerifiedFetch } from '@helia/verified-fetch'
-
-const verifiedFetch = await createVerifiedFetch({
-  gateways: ['https://rainbow-gateway.example.net'],
-  routers: ['https://someguy-routing.example.net']
-})
-
-const res = await verifiedFetch('ipfs://bafy.../path/to/file')
-```
-
-Replace the example domains with your own. See the [`@helia/verified-fetch` README](https://www.npmjs.com/package/@helia/verified-fetch) for the current option names.
-
-### Point your own Kubo or Rainbow at Someguy (optional)
-
-Since Someguy caches routing answers, you can also point your backend Kubo or Rainbow node at it. By default both reach out to public delegated routing endpoints; this override sends them through your Someguy instead. Skip this step if you do not run a backend node.
-
-For Kubo, override the delegated routers and restart the daemon:
-
-```bash
-ipfs config --json Routing.DelegatedRouters '["https://someguy-routing.example.net/routing/v1"]'
-```
-
-For Rainbow, set the env var before startup:
-
-```bash
-RAINBOW_HTTP_ROUTERS=https://someguy-routing.example.net/routing/v1
-```
-
 ## Further reading
 
 - [Service Worker Gateway](https://github.com/ipfs/service-worker-gateway#readme): worked end-to-end example built on `@helia/verified-fetch`. Useful if you want a single web entry point that handles all IPFS URLs in your app.

From 9e3ce6c10760874f45034f1923cfb55a6ba2b920 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 29 May 2026 16:26:49 +0200
Subject: [PATCH 3/6] docs: fix two grammar nits in gateway guide

Address the legitimate LanguageTool findings; the rest were false
positives on code fences, domains, and shell snippets.

- add comma after introductory "By default"
- "install steps" -> "installation steps"
---
 docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
index 4e8bbd75e..4c000e4c3 100644
--- a/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
+++ b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md
@@ -101,7 +101,7 @@ Replace the example domains with your own. See the [`@helia/verified-fetch` READ
 
 ### Point your own Kubo or Rainbow at Someguy (optional)
 
-Since Someguy caches routing answers, you can also point your backend Kubo or Rainbow node at it. By default both reach out to public delegated routing endpoints; this override sends them through your Someguy instead. Skip this step if you do not run a backend node.
+Since Someguy caches routing answers, you can also point your backend Kubo or Rainbow node at it. By default, both reach out to public delegated routing endpoints; this override sends them through your Someguy instead. Skip this step if you do not run a backend node.
 
 For Kubo, override the delegated routers and restart the daemon:
 
@@ -121,7 +121,7 @@ RAINBOW_HTTP_ROUTERS=https://someguy-routing.example.net/routing/v1
 
 ### Run it
 
-Follow the install steps in the [Rainbow README](https://github.com/ipfs/rainbow#readme). Once running, Rainbow serves a gateway on `http://127.0.0.1:8090` by default.
+Follow the installation steps in the [Rainbow README](https://github.com/ipfs/rainbow#readme). Once running, Rainbow serves a gateway on `http://127.0.0.1:8090` by default.
 
 ### Swap your URLs
 

From 38800e60bbede5097c810870e0013e566dd4e3bc Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 29 May 2026 17:06:22 +0200
Subject: [PATCH 4/6] ci: quiet languagetool reviewdog noise

Switch the reporter to check-run annotations and silence rules that
misfire on code and domains, so pushes stop stacking duplicate review
comments and addressed findings clear themselves.

- reporter github-pr-review -> github-pr-check (annotations replace per
  run, no duplicate comments, fixed findings drop on the next run)
- disable rules that fire on code fences, inline code, shell snippets,
  and domain names, on top of the action defaults
---
 .github/workflows/reveiwdog-languagetool.yml | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/reveiwdog-languagetool.yml b/.github/workflows/reveiwdog-languagetool.yml
index 77a20c6c2..1ea154e26 100644
--- a/.github/workflows/reveiwdog-languagetool.yml
+++ b/.github/workflows/reveiwdog-languagetool.yml
@@ -13,7 +13,14 @@ jobs:
         uses: reviewdog/action-languagetool@v1
         with:
           github_token: ${{ secrets.github_token }}
-          reporter: github-pr-review
+          # github-pr-check posts findings as check-run annotations instead of
+          # review comments. Each run replaces the previous run's annotations, so
+          # pushes do not pile up duplicate comments and fixed findings disappear
+          # on the next run, rather than lingering as stale review threads.
+          reporter: github-pr-check
           level: info
+          # Action defaults plus rules that misfire on code fences (```js), inline
+          # code, shell snippets (quotes), and domain names (ipfs.io) in our docs.
+          disabled_rules: WHITESPACE_RULE,EN_QUOTES,DASH_RULE,WORD_CONTAINS_UNDERSCORE,UPPERCASE_SENTENCE_START,ARROWS,COMMA_PARENTHESIS_WHITESPACE,UNLIKELY_OPENING_PUNCTUATION,SENTENCE_WHITESPACE,CURRENCY,EN_UNPAIRED_BRACKETS,PHRASE_REPETITION,PUNCTUATION_PARAGRAPH_END,METRIC_UNITS_EN_US,ENGLISH_WORD_REPEAT_BEGINNING_RULE,FILE_EXTENSIONS_CASE,EN_UNPAIRED_QUOTES,A_INSTALL,LC_AFTER_PERIOD
           patterns: 'docs/**/*.md'
 

From c06c1f5ece3de72b32c93707307640224fefacc9 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 29 May 2026 17:22:46 +0200
Subject: [PATCH 5/6] ci: fix vale vocab and dead links

Touching ipfs-gateway.md made the link checker scan it and surfaced two
pre-existing dead links; the prose also used terms missing from the
Vale vocabulary.

- accept.txt: add hotlink, subresource, navigation, deserialize, env
- ipfs-gateway: gateway-troubleshooting.md -> troubleshooting.md
- mlc config: ignore gnu.org (valid URL, 403s the checker bot)
---
 .github/styles/Vocab/ipfs-docs-vocab/accept.txt | 5 +++++
 docs/concepts/ipfs-gateway.md                   | 2 +-
 mlc_pull_req_config.json                        | 3 +++
 3 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/styles/Vocab/ipfs-docs-vocab/accept.txt b/.github/styles/Vocab/ipfs-docs-vocab/accept.txt
index a107355ab..06d5fe8dd 100644
--- a/.github/styles/Vocab/ipfs-docs-vocab/accept.txt
+++ b/.github/styles/Vocab/ipfs-docs-vocab/accept.txt
@@ -227,3 +227,8 @@ denylist
 IPFS's
 IPIPs?
 _redirects
+[Hh]otlink(ed|ing|s)?
+[Ss]ubresources?
+[Nn]avigations?
+[Dd]eserialize[sd]?
+env
diff --git a/docs/concepts/ipfs-gateway.md b/docs/concepts/ipfs-gateway.md
index 704e91ae9..dc6fd9147 100644
--- a/docs/concepts/ipfs-gateway.md
+++ b/docs/concepts/ipfs-gateway.md
@@ -191,7 +191,7 @@ Currently HTTP gateways typically expose both immutable IPFS and mutable IPNS (e
 
 ## Working with gateways
 
-For more information on working with gateways, see [best practices](../how-to/gateway-best-practices.md) and [troubleshooting](../how-to/gateway-troubleshooting.md).
+For more information on working with gateways, see [best practices](../how-to/gateway-best-practices.md) and [troubleshooting](../how-to/troubleshooting.md).
 
 ## Implementing gateways
 
diff --git a/mlc_pull_req_config.json b/mlc_pull_req_config.json
index 9a71e6e52..b3eaabfec 100644
--- a/mlc_pull_req_config.json
+++ b/mlc_pull_req_config.json
@@ -13,6 +13,9 @@
         },
         {
             "pattern": "^https://www.npmjs.com/"
+        },
+        {
+            "pattern": "^https://www.gnu.org/"
         }
     ],
     "aliveStatusCodes": [200, 206, 429]

From bf5b5511e81b0b92fe5ba29680c9e493e9ac16c2 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Fri, 29 May 2026 17:27:02 +0200
Subject: [PATCH 6/6] ci: put spelling exceptions in the file vale actually
 reads

The vale Vocab is not enabled in .vale.ini, so accept.txt was dead
config; PLNSpelling reads pln-ignore.txt. Move the words there and
revert the accept.txt change.

- pln-ignore: deserializes, dnslinks, env, fastly, hotlinked, iostat,
  iotop, navigations, speedtest, subresource(s)
---
 .github/styles/Vocab/ipfs-docs-vocab/accept.txt |  5 -----
 .github/styles/pln-ignore.txt                   | 11 +++++++++++
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/.github/styles/Vocab/ipfs-docs-vocab/accept.txt b/.github/styles/Vocab/ipfs-docs-vocab/accept.txt
index 06d5fe8dd..a107355ab 100644
--- a/.github/styles/Vocab/ipfs-docs-vocab/accept.txt
+++ b/.github/styles/Vocab/ipfs-docs-vocab/accept.txt
@@ -227,8 +227,3 @@ denylist
 IPFS's
 IPIPs?
 _redirects
-[Hh]otlink(ed|ing|s)?
-[Ss]ubresources?
-[Nn]avigations?
-[Dd]eserialize[sd]?
-env
diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt
index 16aec32c0..14e7e21cd 100644
--- a/.github/styles/pln-ignore.txt
+++ b/.github/styles/pln-ignore.txt
@@ -353,3 +353,14 @@ youtube
 zarr
 Zeeshan
 Zelenka
+deserializes
+dnslinks
+env
+fastly
+hotlinked
+iostat
+iotop
+navigations
+speedtest
+subresource
+subresources