From 35a4eef05727b380dfdff76b58d5cd7219f35446 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Sun, 9 Nov 2025 19:08:50 +0100 Subject: [PATCH] chore: remove mentions of gateway.ipfs.io Replace gateway.ipfs.io with gateway.example.net placeholder and add explanatory callout boxes. The gateway.ipfs.io domain is a legacy domain that caused unnecessary request duplication and should no longer be used in documentation. Users are now directed to use either: - Self-hosted Kubo gateways - Public good ipfs.io for testing - Other public gateways with subdomain isolation support --- docs/how-to/host-git-repo.md | 8 ++++++- docs/how-to/host-single-page-site.md | 22 ++++++++++++------- .../websites-on-ipfs/multipage-website.md | 10 +++++++-- 3 files changed, 29 insertions(+), 11 deletions(-) diff --git a/docs/how-to/host-git-repo.md b/docs/how-to/host-git-repo.md index a6d3517f7..ee4fd4ee2 100644 --- a/docs/how-to/host-git-repo.md +++ b/docs/how-to/host-git-repo.md @@ -10,6 +10,12 @@ Have you ever said to yourself: "Man, my Git server isn't distributed enough" or In this guide, we discuss how to serve a Git repository through the IPFS network. The end result will be a `git clone`able URL served through IPFS! +:::callout +This guide uses `gateway.example.net` as a placeholder for an IPFS gateway. You can replace it with: +- A self-hosted [Kubo](../install/command-line.md) gateway +- For best-effort hosting and testing try [public good `ipfs.io` (`dweb.link` variant)](../concepts/public-utilities.md#public-ipfs-gateways), or any of the [public gateways](https://ipfs.github.io/public-gateway-checker/) that support "Origin" isolation ([subdomain mode](./address-ipfs-on-web.md#subdomain-gateway)) +::: + To start, select a Git repository you want to host, and do a bare clone of it: ```bash @@ -71,7 +77,7 @@ paths will now look something like: ```go import ( - mylib "gateway.ipfs.io/ipfs/QmX679gmfyaRkKMvPA4WGNWXj9PtpvKWGPgtXaF18etC95" + mylib "gateway.example.net/ipfs/QmX679gmfyaRkKMvPA4WGNWXj9PtpvKWGPgtXaF18etC95" ) ``` diff --git a/docs/how-to/host-single-page-site.md b/docs/how-to/host-single-page-site.md index fe339570a..6e8fecf33 100644 --- a/docs/how-to/host-single-page-site.md +++ b/docs/how-to/host-single-page-site.md @@ -11,6 +11,12 @@ A great way to get to know IPFS is to use it to host a simple, single-page websi We've put together a series of tutorials to walk you through hosting a full website on IPFS. [Take a look!](websites-on-ipfs/single-page-website.md) ::: +:::callout +This guide uses `gateway.example.net` as a placeholder for an IPFS gateway. You can replace it with: +- A self-hosted [Kubo](../install/command-line.md) gateway +- For best-effort hosting and testing try [public good `ipfs.io` (`dweb.link` variant)](../concepts/public-utilities.md#public-ipfs-gateways), or any of the [public gateways](https://ipfs.github.io/public-gateway-checker/) that support "Origin" isolation ([subdomain mode](./address-ipfs-on-web.md#subdomain-gateway)) +::: + ## Create your site Assume you have a static website in a directory `mysite`. @@ -37,7 +43,7 @@ The last hash, next to the folder name, `mysite/` is the one to remember, call i You can test it out locally by opening `http://localhost:8080/ipfs/$SITE_CID` in a browser or with `wget` or `curl` from the command line. -To view it from another ipfs node, you can try `http://gateway.ipfs.io/ipfs/$SITE_CID` in a browser. This will work from a browser on another device, inside or outside the network where you added the site's file. +To view it from another ipfs node, you can try `http://gateway.example.net/ipfs/$SITE_CID` in a browser. This will work from a browser on another device, inside or outside the network where you added the site's file. Those hashes are difficult to remember. Let's look at some ways to get rid of them. @@ -56,7 +62,7 @@ your.domain. 60 IN TXT "dnslink=/ipfs/$SITE_CID" Now you can view your site at `http://localhost:8080/ipns/your.domain`. -You can also try this on the gateway at `http://gateway.ipfs.io/ipns/your.domain`. +You can also try this on the gateway at `http://gateway.example.net/ipns/your.domain`. More questions about DNSLink? Check out the [DNSLink website](http://dnslink.io/) for tutorials, examples, and FAQs. @@ -79,9 +85,9 @@ Published to $PEER_ID: /ipfs/$SITE_CID You will need to note and save that value of `$PEER_ID` for the next steps. -Load the URLs `http://localhost:8080/ipns/$PEER_ID` and `http://gateway.ipfs.io/ipns/$PEER_ID` to confirm this step. +Load the URLs `http://localhost:8080/ipns/$PEER_ID` and `http://gateway.example.net/ipns/$PEER_ID` to confirm this step. -Return to your registrar's control panel, change the DNS TXT record with the key of `your.domain` to `dnslink=/ipns/$PEER_ID`, wait for that record to propagate, and then try the URLs `http://localhost:8080/ipns/your.domain` and `http://gateway.ipfs.io/ipns/your.domain`. +Return to your registrar's control panel, change the DNS TXT record with the key of `your.domain` to `dnslink=/ipns/$PEER_ID`, wait for that record to propagate, and then try the URLs `http://localhost:8080/ipns/your.domain` and `http://gateway.example.net/ipns/your.domain`. **Note:** When using IPNS to update websites, assets may be loaded from two different resolved hashes while the update propagates. This may result in outdated URLs or missing assets until the update has completely propagated. @@ -91,10 +97,10 @@ You now have a website on ipfs/ipns, but your visitors can't access it at `http: What we can do is have requests for `http://your.domain` resolved by an IPFS gateway daemon. -Return to your registrar's control panel and add an A record with key of `your.domain` and value of the IP address of an ipfs daemon that listens on port 80 for HTTP requests (such as `gateway.ipfs.io`). If you don't know the IP address of the daemon you plan to use, you can find it using the command like: +Return to your registrar's control panel and add an A record with key of `your.domain` and value of the IP address of an ipfs daemon that listens on port 80 for HTTP requests (such as `gateway.example.net`). If you don't know the IP address of the daemon you plan to use, you can find it using the command like: ```bash -$ nslookup gateway.ipfs.io +$ nslookup gateway.example.net ``` 1. Note the IP addresses returned. @@ -105,7 +111,7 @@ Note: The ipfs.io gateway IP addresses won't change, so you can set them and for Visitors' browsers will send `your.domain` in the Host header of their requests. The ipfs gateway will recognize `your.domain`, look up the value of the DNS TXT for your domain, then serve the files in `/ipns/your.domain/` instead of `/`. -If you point `your.domain`'s A and AAAA record to the IP addresses of `gateway.ipfs.io`, and then wait for the DNS to propagate, then anyone should be able to access your ipfs-hosted site without any extra configuration at `http://your.domain`. +If you point `your.domain`'s A and AAAA record to the IP addresses of `gateway.example.net`, and then wait for the DNS to propagate, then anyone should be able to access your ipfs-hosted site without any extra configuration at `http://your.domain`. ## Use CNAMEs @@ -113,4 +119,4 @@ Alternatively, it is possible to use CNAME records to point at the DNS records o However you will need to change the key for the TXT record from `your.domain` to `_dnslink.your.domain`. -So by creating a CNAME for `your.domain` to `gateway.ipfs.io` and adding a `_dnslink.your.domain` record with `dnslink=/ipns/` you can host your website without explicitly referring to IP addresses of the ipfs gateway. +So by creating a CNAME for `your.domain` to `gateway.example.net` and adding a `_dnslink.your.domain` record with `dnslink=/ipns/` you can host your website without explicitly referring to IP addresses of the ipfs gateway. diff --git a/docs/how-to/websites-on-ipfs/multipage-website.md b/docs/how-to/websites-on-ipfs/multipage-website.md index 617c9031f..bd4ca6ffa 100644 --- a/docs/how-to/websites-on-ipfs/multipage-website.md +++ b/docs/how-to/websites-on-ipfs/multipage-website.md @@ -7,6 +7,12 @@ description: Learn how to host a website with multiple pages and external assets In this guide, you will learn how to host a website with multiple pages and external assets on IPFS. This tutorial is the second in a series of tutorials aimed at teaching web developers how to build websites and applications using IPFS. You don't need to have completed the previous tutorial to understand what's going on here, but if you're new to the IPFS ecosystem, it's a good idea to follow through the [single page website guide](../../how-to/websites-on-ipfs/single-page-website.md) before you start this one. It will give you a solid foundation to work off. +:::callout +This guide uses `gateway.example.net` as a placeholder for an IPFS gateway. You can replace it with: +- A self-hosted [Kubo](../../install/command-line.md) gateway +- For best-effort hosting and testing try [public good `ipfs.io` (`dweb.link` variant)](../../concepts/public-utilities.md#public-ipfs-gateways), or any of the [public gateways](https://ipfs.github.io/public-gateway-checker/) that support "Origin" isolation ([subdomain mode](../address-ipfs-on-web.md#subdomain-gateway)) +::: + ## Prerequisites If you followed the previous tutorial, you would already have the IPFS Desktop application installed. If not, you can grab it from the [IPFS Shipyard](https://github.com/ipfs-shipyard/ipfs-desktop). @@ -217,7 +223,7 @@ Instead of sharing the CID of your website, you publish the root CID of your web The `k51qzi...` is your IPFS installation's key! This is what you can use to point people to your content. -1. You should now be able to view your project by going to `https://gateway.ipfs.io/ipns/k51qzi...`. Replace `k51qzi...` with the output from the previous step. +1. You should now be able to view your project by going to `https://gateway.example.net/ipns/k51qzi...`. Replace `k51qzi...` with the output from the previous step. 1. Whenever you make any changes to your project, simply re-add your content to IPFS and publish it to IPNS: ```shell @@ -232,7 +238,7 @@ Instead of sharing the CID of your website, you publish the root CID of your web > Published to k51qzi5uqu5dh9gnl66grpnpuhj245ha1xq9ajtmuf7swe847zovdg1t9a0xiz: /ipfs/QmchJPQNLE5EUSYTzfzUsNFyPozXyANiZHFDSFKWdLNdRR ``` - Now, just head back to the `https://gateway.ipfs.io/ipns/k51qzi...` link to view your updates! + Now, just head back to the `https://gateway.example.net/ipns/k51qzi...` link to view your updates! This is just the tip of the iceberg when it comes to IPNS. [Check out the IPNS page to learn more →](../../concepts/ipns.md)