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 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' diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 775624d62..9d46ffb3a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -293,6 +293,7 @@ module.exports = { collapsable: true, children: [ '/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..dc6fd9147 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. @@ -189,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/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/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/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 new file mode 100644 index 000000000..4c000e4c3 --- /dev/null +++ b/docs/how-to/replace-public-gateways-with-self-hosted-ipfs.md @@ -0,0 +1,234 @@ +--- +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 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 (``, `