A Guide to Hosting Websites on IPFS

How to host a site on the Inter-Planetary File System

Photo by David Menidrey on Unsplash

In this post, I will describe how to host a website on the Inter-Planetary File System (IPFS), a peer-to-peer network for storing and accessing files, webpages, data, etc across a network of computers. Decentralized storage protocols, such as IPFS, will play an integral in the web3 technology stack, helping to make the internet decentralized and immutable. I believe this nascent protocol will be an important component of the internet in the coming years.

There are many uses for this protocol, but in this post, I will focus solely on hosting a website. Keep in mind that the IPFS protocol is currently not natively supported in all browsers yet, which can limit the reach of your content. For those IPFS-ignorant browsers, we can simply route our webpage through a “gateway.” This is what I will be showcasing in this post. As an example, here is my webpage hosted on IPFS routed through a gateway.

Table of contents
0. A brief overview of IPFS
  0.1 Content Identifiers (CID)
  0.2 Gateway Servers
  0.3 Where to go from here
1. Install IPFS CLI
  1.1 Brief tutorial of IPFS
2. Upload your website to IPFS
3. Connecting IPFS to your own domain name
  3.1 DNS link domain to IPFS
  3.2 What actually happens?
4. Conclusions

0. A brief overview of IPFS

One of the main differences between IPFS and the ubiquitous hypertext transfer protocol (HTTP) is the way data is referenced. HTTP references by location while IPFS references by content. When you enter a uniform resource locator (URL) into your browser (e.g. www.medium.com) you are specifying the location of the content you want to access.

However, maybe the person next to you at the coffee shop has a copy of the content you are asking for. So why not get it from them? This is possible with IPFS where multiple “peers” can host the same content allowing you to retrieve it from any of them instead of a central server. Files on IPFS may not be stored in just one place but in many places around the world, and someday maybe even on other planets (hence the name inter-planetary file system).

When asking for content on IPFS, we specify what we want with a content identifier (CID), regardless of where it is located. This CID is a cryptographically unique hash of the content. Thus, if the content changes then the CID will change. This is important to ensure the content was not tamped with.

IPFS makes the internet immutable and resilient. The CID is unique to the content and thus if the content is changed then a new CID is generated. The data is resilient since it is hosted on multiple computers, making it difficult to be completely removed from the network.

0.1 Content Identifiers (CID)

A CID is analogous to a URL. While a URL describes the location of a server, a CID describes the content itself, regardless of where it is located. Put simply, IPFS asks computers connected to you “do you know where the content associated with this CID is located?” To which a computer in the network will respond, “yes, you can find the content at this server.”

As an example, here is the CID to the IPFS Wikipedia mirror:

ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco

Just like a file system, we can navigate to the content we really want.

ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Beatles.html

The challenge with this system is that most browsers do not know how to resolve an IPFS address. Brave and Opera are two browsers with native IPFS support. For the IPFS-ignorant browsers, we have to either install the IPFS companion or rely on a “gateway”.

0.2 Gateway servers

A gateway is a middleman between your browser and IPFS. You make an HTTP request to a centralized gateway server that then fetches IPFS content.

Schematic of how an IPFS gateway works. Requests are routed through a centralized gateway server and then the content on IPFS is retrieved and sent back to the user. (image source: modified UnDraw image by author)

Gateways allow anybody to access IPFS content (regardless of your browser), the downside is that the server is centralized and thus prone to being off-line. This is one problem with gateway servers.

Although a gateway is centralized and could permanently go offline, the content itself is still preserved on IPFS. The gateway may be gone, but the content itself still persists— assuming it is pinned to a node in the network.

As an example, here is the same Beatles page as before routed through the https://dweb.link gateway:

https://dweb.link/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/wiki/Beatles.html

0.3 Where to go from here

Now that we understand a little bit about IPFS and how it works, let’s install IPFS and host some of our own content!

1. Install IPFS CLI

On macOS, you can use brew to install IPFS

brew install ipfs

This will install the IPFS command-line interface (CLI).

Or you can download it directly from ipfs.io

Command-line | IPFS Docs

Ensure the CLI is installed by checking the version.

ipfs --version

1.1 Brief tutorial of IPFS

Before we can start using IPFS, we need to initialize the repository

ipfs init

This creates files in ~/.ipfs to store settings and internal data.

We can connect to the network by starting the daemon in a new session.

ipfs daemon

The daeman can be started in the background as well. ipfs daemon & , just don’t forget to stop it. On macOS, killall ipfs will stop the daemon.

Keep the daemon running so you can view content in your browser.

let’s now add some content to the network and save the CID to a variable.

CID=`echo "I <3 IPFS -$(whoami)" | ipfs add -q`

This will always generate the same CID, even if I change $(whoami) to my actual username. This is because IPFS is hashing the content. Therefore, if the content doesn’t change, then the hash (i.e. CID) wont change.

Use the following to view the CID of the content you just added

echo $CID

On my machine, the CID is: QmTUoo1hN87Vq8rjK9XbJgE6W2ZpHQLshTq31ZsrSLnGWT

You can view the content you just added with ipfs cat

ipfs cat QmTUoo1hN87Vq8rjK9XbJgE6W2ZpHQLshTq31ZsrSLnGWT

Try resolving the CID via a gateway (e.g. https://dweb.link/ipfs/CID). For example, here is how I could resolve my CID.

https://dweb.link/ipfs/QmTUoo1hN87Vq8rjK9XbJgE6W2ZpHQLshTq31ZsrSLnGWT

You should see your message displayed in the browser.

This is great! We can successfully upload content to IPFS and view it in a browser. Now let’s add a full webpage.

2. Upload your website to IPFS

You will need a website to host. Here, I am not going to do anything fancy and just use vanilla HTML, CSS, and JavaScript with the following structure.

.
├── index.html
├── css
│   └── styles.css
├── img
│   └── image.png
└── javascript
    └── scripts.js

Just like before, we can add the directory with ipfs add -r <site_dir>

ipfs add -r .

The -r flag adds recurively and the “.” indicates we are running the command from the webpage directory.

You will notice that each item in the directory tree has a CID. All we care about is the top-level CID pointing to the entire website.

Just like before, we can view the webpage via a gateway

ipfs.io/ipfs/QmdJcNS1M42rjBT6mnfEuE1oTqP5nGWt3msgFA9KH36a9e/

but you probably don’t want to be telling people you have a cool webpage at ipfs.io/ipfs/QmdJcNS1M42rjBT6mnfEuE1oTqP5nGWt3msgFA9KH36a9e/

One solution is to purchase a domain name and link to content on IPFS.

3. Connecting IPFS to your own domain name

This step requires a domain name that you own. I purchased my domain name through Cloudflare, but any provider should work.

We will use DNSLink to map the IPFS CID to our domain address.

3.1 DNS link domain to IPFS

You will need a DNS provider. I am using Cloudflare, but the basic instructions should hold for any DNS provider.

1. Log into Cloudflare
2. Click on your active website and then on DNS in the left-hand column.
3. DNS management section, add a TXT and CNAME record.
4. Set the TXT record name to _dnslink.yourwebsite.com (make sure to replace yourwebsite.com with your own domain)
5. Set the TXT record content to dnslink=/ipfs/CID (make sure replace CID with your own)
6. Set the CNAME record to any IPFS gateway (e.g. gateway.ipfs.io )

As an example, here is a screenshot of my TXT and CNAME records.

image by author

Ensure there isn’t a leading or trailing blank space when copying a CID

Once you enter all the information, click save and you will have successfully hosted your website on IPFS.

3.2 What actually happens?

Your browser performs a DNS lookup to get the IP address of the gateway server. The gateway notices the request is coming from your webpage and it will look for the DNS entry with the IPFS address to the content. The gateway will retrieve the content from IPFS and return it to your browser.

4. Conclusions

In this post, I provided one solution to host a webpage on IPFS and have it be viewable view anybody. Hosting a website on IPFS is easy, but does require a little bit of work (and money) to have a human-readable domain name.

The solution works, but it is cumbersome to keep changing the IPFS address in the TXT record each time you update the webpage. As a solution to this, I encourage you to check out the Inter-Planetary Name System (IPNS). I also suggest checking out the IPFS GitHub Action and Unstoppable Domains, if you want a completely decentralized website with a human-readable domain name (at the time of writing, browser support is limited with this approach.)

Another issue with the solution is accessibility. To ensure your content is always available it is best to “pin” your content to multiple nodes. I encourage you to check out different pinning services which make this easy. Piñata is one such service where you can pin a lightweight website using a free account.

Hosting a website is one of many use cases that exist for this emerging technology. An obvious application is a decentralized storage solution.

I for one am extremely excited by this emerging technology and look forward to seeing what is in store for the future. If you want to learn more I encourage you to check out the IPFS docs and browser the tutorials in this gitbook.

Want to Connect?

L. Gloege