Ben Hayward

Hosting a Hugo blog in IPFS

Hugo & IPFS

Hugo is a static site generator which provides an quick and simple website, like this one.

IPFS (InterPlanetary File System) defines itself as ‘a peer-to-peer hypermedia protocol to make the web faster, safer, and more open.’. It is a system has been created not too dissimilar from BitTorrent, but fundamentally different in a few ways. At its core IPFS is a file-system that uses the hash of a file as the content address - As the same file will always hash to the same value, if multiple people share the same file, they are pointing at the same address, irregardless of when and where they are uploading from. it offers the world a cheap, immutable, uncensored alternative to the HTTP protocol.

Why host a site on IPFS?

One advantage of IPFS is that it provides the opportunity for a person to create an inexpensive quick to set-up static website. In this tutorial, we will be creating a personal blog!

One of the main disadvantages currently IPFS is that it is not yet optimized enough to support more-complicated web applications. You will have to stick to lightweight static websites. This, makes it absolutely perfect to use a static site generator such as Hugo. Here we are going to grab an existing Hugo template, but if you would like to create your own website from scratch then feel free to skip down.

Great! How do I start?

Well. The more personal thing would be to create your own static website. There is no server in IPFS, so if you want a more dynamic page - feel free to look into client side databases like GunDB, or even OrbitDB - Which itself uses IPFS.

If you are looking for a no hassle, easy and quick solution, you can use Hugo as will be demonstrated in this blog. Hugo is a static site generation tool, that just requires a little tinkering and some simple commands to create a website from templates.

Install Hugo

Head on over to and follow the instructions.

Setting up the site

Firstly, in your terminal, pick a directory for your site, and run:

hugo new site [[folder name]]
cd [[folder name]]

Okay, you’re now in the project root for your site. You’re going to want to fine a theme

When you’ve found one, follow the installation instructions in the README. Install the theme into the project root, configure the config.toml how you like.

Running the site

You can see the chosen site through

hugo serve

be warned, hugo serve does not take into account pathing in the same way a browser does, so what you see may not be what you get when you put it on IPFS. Lets see.

Installing IPFS

Time for another installation guide!

When you’re done, run:

ipfs daemon

in a shell to get the daemon running.

Deploy IPFS

All ready to go? Fantastic, now its time to make a test deploy to IPFS to verify that IPFS is going to play nicely with this theme. From your project root, run:

ipfs add -r public

At the output, grab the hash for the outermost public folder, at the bottom, and enter it into a browser at http://localhost:8080/ipfs/{{your hash}}

Did it work?

If the site looks correct, have a navigate around to some other pages. Make sure everything is loading properly in your XHRs, if it is, great, you can skip this step, if its not, don’t panic too much.

Red XHR requests

Firstly, open your dev tools and refresh the half loaded page. If you inspect the XHRs, you will likely see that the URLs are messed up.

Messed up URLs

Relative URLs are key

Because of how IPFS works, absolute links are not going to work for us. A lot of Hugo themes use absolute URLs, so you have two options; make some changes to the source files of the theme you are using or make some changes. Lets do this the non-lazy way.

You’re going to need to run a scan of the codebase of your theme for any references to BaseURL, like you can see here:

We need to edit them to use RelUrl.

Now, try deploying to IPFS again!

Make some content

Finally, make some content. For your site, and publish it! You can host your site over at, or another service like Eternum. For better speed, access through a quality gateway like{{hash}}. You can also pin the site locally by using:

ipfs pin add {{hash}}

I’ll continue this series in the future to discuss the use of DNSLink and IPNS.