I’ve always been fascinated by the idea of peer-to-peer network protocols, and putting my website on a distributed network was something I’ve been meaning to do for a while. The recent increase in blog posts about IPFS finally pushed me over the tipping point. Hopefully, you can read this article on IPFS here.

I am really happy with this change, and I urge everyone to do the same with their websites. IPFS may or may not be the perfect solution to the decentralized web, but we need to start somewhere. In this article, I will try to give a step-by-step guide for putting static websites on IPFS.

Getting started

First, a bit about getting your feet wet with IPFS. Every file and directory in IPFS can be referenced by a hash that looks like QmNiMm9LUX9R4Ezu2NAsraxFSyrbNR6rgGwCDu71Dy4NwQ. If you have it installed on your computer, you can go on the command line to download and view files.

ipfs cat QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u

This command will output ‘Hello World’. I chose this as an example, because I assume hello world is something a lot of people will have on their nodes.

Just as easy as getting files, putting files is also easy. Lets say you have a picture of a cat called kitten.jpg. Running ipfs add kitten.jpg give you a hash and your node will start seeding it. You can just give that hash to people you want to share the file with. You can try it like this.

Putting a website on IPFS

So how do we go from putting up a file there to putting up a whole website? Just like most unix commands, IPFS also accepts the parameter -r for running the command recursively. Let’s say our website is in the public/ directory. If we run ipfs add -r public/, it will first add all the files and subdirectories into IPFS, and finally give us a hash that represents the whole folder.

Other people can view your website with that hash. The hash changes if you update your website, but you can solve this issue with IPNS. IPNS basically allows you use a private key to update the contents of your files. As long as you have your private key, you can publish updates to your IPFS website.

If you want to use IPNS (you probably do), you need to run ipfs name publish <the hash of the folder>. After doing these, you can give your IPNS hash to people, and whenever you update your website they will see the updated version as well.

But as a person who has keeps losing private keys, I can just use my domain’s DNS records to change the hash whenever I need to.

Using DNS for IPFS

If you don’t want to deal with giving out long hashes to people, IPFS allows you to use your normal domain as well. To do this, you need to add a line to your DNS records.

Just go to your domain’s DNS settings, and find where to add a TXT record. In the content, you should write dnslink=/ipfs/<your hash here> or dnslink=/ipns/<your hash here> depending on what you use.

As an example, you can access my blog from /ipns/gkbrk.com.

Hugo Specific Fixes

When you are hosting your website on IPFS, one issue you should be careful of is relative vs. absolute links. If the linking is wrong, you will have issues when people try to navigate your website.

In your Hugo config file (config.toml), you should comment out baseurl and set relativeURLs to true.

# baseurl = ''
relativeURLs = true

If there are still issues, you can fix them whenever you come across them incrementally.


After all these steps, you should be able to successfully host your website on IPFS. If you do it, make sure to let me know by sending an email, a tweet or comment on where you’re reading this from.