Browsing IPFS

Browsing IPFS using Cloudflare’s gateway requires two things: a browser connected to the internet, and the address of something on IPFS that you want to view.

Viewing Content

As mentioned on the About IPFS page, every file added to the IPFS network is given an unique address based on its contents. So if you have an image stored on IPFS, its IPFS address would be based on the hash of the bits that compose that image.

If you have the address of a piece of content you want to view or download, you can do so through Cloudflare’s IPFS gateway. Each time you access a piece of content through Cloudflare’s gateway, you provide a URL with two parts:

  1. The name of the gateway. This never changes: cloudflare-ipfs.com
  2. The file path. That’s generally going to look like: /ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco. The /ipfs/ tells the gateway that you’re providing the address of a piece of content stored on IPFS. The QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco is the address itself.

Put those two components all together and the URL you’ll be providing looks like this:

cloudflare-ipfs.com/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco

You can try that URL out right now!

Directories on IPFS

Note that it’s not just individual files that have IPFS addresses. Directories uploaded to IPFS also get addresses. For example, let’s say you have a folder called example, and that folder has exactly one file, example_text.txt, which contains the string I'm trying out IPFS.

If that folder were added to the IPFS network, both the folder, example, and the file it contains, example_text.txt, would be assigned addresses. In this case, the folder would have the address QmdbaSQbGU6Wo9i5LyWWVLuU8g6WrYpWh2K4Li4QuuE8Fr while the file would have the address QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy.

You could then access the file in two ways.

  1. The hash of the file itself: cloudflare-ipfs.com/ipfs/QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy.
  2. The hash of the parent folder plus the name of the file: cloudflare-ipfs.com/ipfs/QmdbaSQbGU6Wo9i5LyWWVLuU8g6WrYpWh2K4Li4QuuE8Fr/example_text.txt.

InterPlanetary Naming System

If you’ve gotten this far, you know how to load any /ipfs/... file path through Cloudflare’s gateway. Now we’re going to go over how to use one other IPFS system, the InterPlanetary Naming System (IPNS) .

IPNS is a way to address mutable content. Because all of the files on IPFS are addressed by a hash of their content, the address of any given file will change the moment that the file changes. IPNS allows you to give out one constant address that will always point to the most recent version of a file.

Here’s how it works. Every node in the IPFS network has an address called a PeerID (also known as a NodeID), produced by hashing the node’s public key. Because the IPFS network uses the same hashing algorithm to produce PeerIDs that it uses to produce content addresses each PeerID will generally start with Qm and in all other respects look identical to a content address.

Each node can choose to publish a single file or directory through its PeerID by signing the file’s address with its private key and storing the combined address and signature in the Distributed Hash Table, under its PeerID. If a someone else requests the content published to that node’s PeerID, the IPFS protocol first looks up the signed record, verifies the signature, and then looks up the referenced file. This gives node operators a way to give out one constant address that will never change, even as the underlying content that address points to gets updated.

To access files published to a specific PeerID, you would go to cloudflare-ipfs.com/ipns/<PeerID>. Note that in this case the file path is /ipns/ rather than /ipfs/ to emphasize that this content may change.

The Domain Name System

Finally, the easiest way to browse IPFS is with good old DNS. IPFS multihashes can be stored in special DNS records associated with a domain name, and these DNS records indicate to clients what content should be shown when they navigate to the domain name. The best example of this is the homepage for IPFS itself, ipfs.io which can also be found at cloudflare-ipfs.com/ipns/ipfs.io.

Domains can also be pointed at an IPFS gateway, so that going to the domain in a browser shows the same thing as going to cloudflare-ipfs.com/ipns/.... This way, end users don’t have to know an IPFS gateway is involved at all!