This is an example of how you can use the IPFS: InterPlanetary File System for websites. A guide to hosting your site on IPFS, while learning to use node.js and templates.
You will need some basic knowledge and understanding on Web Design and Web Programming, however while reading this I will help you to deploy your solution in the IPFS network by FREE.
The Webpage Code
For simplicity I am using a simple Landing Page Template you can find here. I made some basic customizations, but overall it is the same page.
This template was taken from cruip.com. Cruip is a gallery of free HTML landing pages for startups. Their aim is to help makers and early-stage startups with high-quality templates to enhance the design standards of their next big project.
If you’re looking for template customizations, or if you’re considering a brand new landing page, you can contact them at firstname.lastname@example.org and they'll be glad to help.
I still want to do it myself, how do I use those templates?
Those are node projects and the idea is to use it as a base template for yours, and you should read and follow the instructions that you will find in the README.md file that I will transcript and extend in this article, so first, ensure that node.js & npm are both installed. If not, choose your OS and installation method from this page and follow the instructions.
Next, use your command line to enter your project directory.
This template comes with a ready-to-use package file called 'package-sample.json'. You just need to rename it to 'package.json', then run 'npm install' to install all of the dependencies into your project.
>mv package-sample.json package.json
You’re ready to go! The installation script will run`npm run watch`. It will start a new server, open up a browser and watch for any SCSS or JS changes in the `src` directory; once it compiles those changes, the browser will automatically inject the changed file(s)!
Run any task by typing `npm run task` (where “task” is the name of the task in the `”scripts”` object).
If you are getting lost here I suggest you to go and read this +15minutes introduction to node.js from Victor Ofoegbu
Ready to publish online?
Take the dist/css/*.css, dist/js/*.js and **/*.html files and copy to another ready to deploy directory.
README.md index.html package.json
dist node_modules src
>cp index.html to_build/
>cp -R dist to_build/
Tip: you can customize the deploy locations directly by changing the package.json file
Now let's add this to_build folder with our site to IPFS. This is quite simple! Simply turn on your daemon:
Warning: You need to have IPFS installed in your computer! You can take my FREE course about IPFS installation and basics here . Also, you can follow the installation instruction on the IPFS install page: https://docs.ipfs.io/introduction/install/
And add the directory containing your website:
>ipfs add -r to_buildadded QmdWEyh4V6XpiD42Gk4zJmjsjuzoGDYhpqmB4ww6dpLf5g to_build/dist/css/style.cssadded QmQT78zwo9iVVRHa4yAPhcT674ni4TLwZoWwn8GNnfx7J4 to_build/dist/js/main.min.jsadded QmeVLhqpN6XYf767Kkzwg51b4RvHi9AjcwQQWnCCDornf1 to_build/index.htmladded QmXHyR5AK9t74iTckEQP3kU2GCeN34f4D1g28PysD7WreQ to_build/dist/cssadded QmTTqN4iQ2EkqQbCyuWnxC1bEiZgRkNn7xTc2SanphsT31 to_build/dist/jsadded QmaqSpPkRcdPhuaAtxpSDR8pyU9bgn3AxGPtgQ7kDYbH7s to_build/distadded QmSVqWFhuSWJnf9Nx76EvLAtKo9UXqK5GK2czWwZsMFBWm to_build78.86 KiB / 79.29 KiB [===============================================] 99.45%>
The very last hash next to the folder name is the one you want, let’s call it
$SITE_HASH for now.
$SITE_HASH = QmSVqWFhuSWJnf9Nx76EvLAtKo9UXqK5GK2czWwZsMFBWm
Now, you can test it out locally by opening
http://localhost:8080/ipfs/$SITE_HASH in your web browser!
Next, to view it coming from another ipfs node, you can try
So now you have your website hosted by free over the IPFS network, once you became more familiarized with the tool you will be starting to think out of the box and including it in your own projects.
Note: depending on the state of the network,
curlmay take a while. The public gateways may be overloaded or having a hard time reaching you.
Get rid of the hashes on IPFS
If you read my post up to this point, you now have your Website published on the IPFS network for free. Cool, right? But those hashes on the URLs are rather ugly. Let’s look at some ways to get rid of them. There are lots of ‘solutions’ out there to address this, including url shorteners and things like that. But currently, one of the easiest solutions is to use a DNS
TXT record on a domain that you control.
So, you can do a simple DNS TXT record, containing
dnslink=/ipfs/$SITE_HASH. 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.
Once that record propagates, you should be able to view your site at
http://localhost:8080/ipns/your.domain. Now that's quite a bit cleaner. You can also try this on the gateway at
Updating the page
Next, you might be asking “well what if i want to change my website, DNS is slow!” Well let me tell you about this little thing called IPNS (note the ‘n’). IPNS is the Interplanetary Naming System, you might have noticed the above link has
/ipns/ instead of
/ipfs/. Ipns is used for mutable content in the ipfs network, it's relatively easy to use, and will allow you to change your website without updating the dns record every time! So how do you use it?
After adding your webpage, simply do:
>ipfs name publish $SITE_HASH
Published to <your peer id>: /ipfs/$SITE_HASH
(Disclaimer: When using IPNS to update websites, it’s important to think about that assets could be loaded from two different resolved hashes when updating your website, leading to outdated/missing assets unless accounted for)
Now, you can test that it worked by viewing:
http://localhost:8080/ipns/<your peer id>. And also try the same link on the public gateway. Once you're convinced that works, let's again hide the hash. Change your DNS TXT record to
dnslink=/ipns/<your peer id>, wait for that record to propagate, and then try accessing
When publish current version of site to IPNS:
>ipfs name publish QmSVqWFhuSWJnf9Nx76EvLAtKo9UXqK5GK2czWwZsMFBWmPublished to QmQ21Eg7NHG4sgzMQtQWUeCzKA5FtdgsyArMifj4enk4JW: /ipfs/QmSVqWFhuSWJnf9Nx76EvLAtKo9UXqK5GK2czWwZsMFBWm
That will return your peerID (QmQ21Eg7NHG4sgzMQtQWUeCzKA5FtdgsyArMifj4enk4JW) and the hash you are publishing to peerID. You can confirm by running
ipfs name resolve <peerID>
After that — you can visit published version of site by link: https://ipfs.io/ipns/<peerID>
Use your own domain
At this point, you have a website on ipfs/ipns, and you may be wondering how you could expose it at
http://your.domain, so that the Internet users of today may access it too without them having to know about any of this. It's actually surprisingly simple to do, all you need for this is your previously created TXT record and to point the A record of
your.domain to the IP address of an ipfs daemon that listens on port 80 for HTTP requests (such as
gateway.ipfs.io). The users' browsers will send
your.domain in the Host header of the requests, and you have your dnslink TXT records, so the ipfs gateway will recognize
your.domain as an IPNS name, and so it will serve from under
/ipns/your.domain/ instead of
So, if you point
your.domain's A record to the IP of
gateway.ipfs.io, and then wait for the DNS to propagate, then anyone should be able to access your ipfs-hosted site without any extra configuration simply at
Alternatively, it is possible to use CNAME records to point at the DNS records of the gateway. This way, IP addresses of the gateway are automatically updated. Note however that CNAME records to not allow for other records, such as a TXT to refer to the ipfs/ipns record. Because of this, ipfs allows to create a DNS TXT record for
So by creating a CNAME for
gateway.ipfs.io and adding a
_dnslink.your.domain record with
dnslink=/ipns/<your peer id> you can host your website without explicitly referring to IP addresses of the ipfs gateway.