Guide for use with custom domains

[2color]

Background

This action takes care of merkleising the build and uploading the CAR to the IPFS network. This leaves open how to view the deployed site, especially when used with a custom domain that's used for DNSLink.

Why doesn't this update DNSLink

This action was designed to be focused, simple, and fast (hence composite action), and deliberately doesn't handle updating DNSLink (or make assumptions about how to build your project). There are many DNS providers, each with their own API, making this difficult to maintain and test. Instead, it gives you the CID as output and you handle it yourself in a separate step.

How do you use this action with a custom domain?

For example, let's say you have the domain docs.ipfs.tech, we should have some guidance on how to wire the domain so it loads a deserialised response (as it works today with Fleek). Deserialised response refers to the normal way of a server returning the index.html payload.

• The current approach is to link (in the PR comment and commit status update) to the Service Worker Gateway with a CID (henceforth referred to as SWGW), because it's decoupled from providers, and will try to fetch the site from whichever IPFS providers it can find.
• If you use bring your own domain and use DNSLink, it can be loaded with the SWGW, but there's a UX problem: the URL is very different from whatever the DNSLink name is.
  • For example, for the DNSLink name ipns.ipfs.network the SWGW URL is https://ipns-ipfs-network.ipns.inbrowser.link/. Another example: ndavd.eth becomes ndavd-eth.ipns.inbrowser.link.
• DNSLink generally solves this as follows:
• The TXT record sets the CID
• The CNAME pointing to a gateway (which needs to have a TLS cert), the gateway server will resolve the DNSlink and load the CID.

Ideas

• Use Cloudflare for DNS and do an HTTP Redirect to the SW URL. This works but 👎: You lose the canonical domain
• Deploy to GH Pages: This could work well for deserialised responses. 👎: cannot set the x-ipfs-* headers
• Use Cloudflare for DNS and proxy requests to the SW URL?
• Deploy to cloudflare pages and set the x-ipfs-* headers with a headers file

[2color]

Regarding the x-ipfs-path and x-ipfs-path headers. Feedback from @lidel

Hm.. iirc we should not stress about doing that, afaik header-based detection is a legacy that was kept alive only because Brave implementations cut many corners. E.g.they refused to do DNSlink lookup for every domain, and used this header as a trigger to do it only on IPFS websites. Now that Brave is no more, we don't need to worry about this – afaik Companion does DNSLink lookup probe for every domain.

From the perspective of robustness, having _dnslink.example.com on your example.com domain is usually the proper way of signaling IPFS support because it does not require you to hit HTTP server to know the website is available on IPFS, and the signaling is pure DNS. Your HTTP traffic may get censored, but if you use trusted DoH endpoint, you will learn about DNSlink and page will load via local gateway.

If we need HTTP-based signaling that "website is on IPFS", im afraid header-based detection will not work with website hosting like github or cloudflare pages where you may not control headers.
For that, we may need a new convention of IPFS tooling creating file at .well-known/ipfs/_dnslink and Clients probing for it via HTTP GET, but we should double check this fixes an actual need. (edited)