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 https://gohugo.io/getting-started/installing/ 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
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! https://docs.ipfs.io/guides/guides/install/
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:
hugo
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.
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.
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 https://pinata.cloud/, or another service like Eternum. For better speed, access through a quality gateway like cloudflare-ipfs.com/ipfs/{{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.