# Host a single-page website
A great way to get to know IPFS is to use it to host a simple, single-page website. Here's a step-by-step guide to doing just that.
You may also wish to look through these contributor-written guides to hosting your site on IPFS:
- Make an Immortal Website using Ethereum Name Service and IPFS by Richard Potter. This tutorial uses the IPFS Desktop application and is more suitable for readers who aren't comfortable with the command-line.
- Complete Beginner's Guide to Deploying Your First Static Website to IPFS by @agentofuser. This tutorial uses the command-line and the author's GitHub repo.
# Create your site
Assume you have a static website in a directory
In order to publish it as a site, install IPFS and make sure your IPFS daemon is running:
$ ipfs daemon
Then add the directory with your website:
$ ls mysite img index.html $ ipfs add -r mysite added QmcMN2wqoun88SVF5own7D5LUpnHwDA6ALZnVdFXhnYhAs mysite/img/spacecat.jpg added QmS8tC5NJqajBB5qFhcA1auav14iHMnoMZJWfmr4k3EY6w mysite/img added QmYh6HbZhHABQXrkQZ4aRRSoSa6bb9vaKoHeumWex6HRsT mysite/index.html added QmYeAiiK1UfB8MGLRefok1N7vBTyX8hGPuMXZ4Xq1DPyt7 mysite/
The last hash, next to the folder name,
mysite/ is the one to remember, call it
$SITE_CID for now.
You can test it out locally by opening
http://localhost:8080/ipfs/$SITE_CID in a browser or with
curl from the command line.
To view it from another ipfs node, you can try
http://gateway.ipfs.io/ipfs/$SITE_CID in a browser. This will work from a browser on another device, inside or outside the network where you added the site's file.
Those hashes are difficult to remember. Let's look at some ways to get rid of them.
# Edit your DNS records
Assume you have the domain name
your.domain and can access your registrar's control panel to manage DNS entries for it.
Create a DNS TXT record (DNSLink), with the key
your.domain. and the value
$SITE_CID is the value from the section above.
Once you've created that record, and it has propagated you should be able to find it.
$ dig +noall +answer TXT your.domain your.domain. 60 IN TXT "dnslink=/ipfs/$SITE_CID"
Now you can view your site at
You can also try this on the gateway at
More questions about DNSLink? Check out the DNSLink website for tutorials, examples, and FAQs.
# Use IPNS
Each time you change your website, you will have to republish it, update the DNS TXT record with the new value of
$SITE_CID and wait for it to propagate.
You can get around that limitation by using IPNS, the InterPlanetary Naming System.
You might have noticed
/ipns/ instead of
/ipfs/ in the updated links in the previous section.
The 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.
To enable the IPNS for your content, run the following command, where
$SITE_CID is the hash value from the first step.
$ ipfs name publish $SITE_CID Published to $PEER_ID: /ipfs/$SITE_CID
You will need to note and save that value of
$PEER_ID for the next steps.
Load the urls
http://gateway.ipfs.io/ipns/$PEER_ID to confirm this step.
Return to your registrar's control panel, change the DNS TXT record with the key of
dnslink=/ipns/$PEER_ID, wait for that record to propagate, and then try the urls
Note: When using IPNS to update websites, assets may be loaded from two different resolved hashes while the update propagates. This may result in outdated URLs or missing assets until the update has completely propagated.
# Point your domain to IPFS
You now have a website on ipfs/ipns, but your visitors can't access it at
What we can do is have requests for
http://your.domain resolved by an IPFS gateway daemon.
Return to your registrar's control panel and add an A record with key of
your.domain and value of the IP address of an ipfs daemon that listens on port 80 for HTTP requests (such as
gateway.ipfs.io). If you don't know the IP address of the daemon you plan to use, you can find it using the command like:
$ nslookup gateway.ipfs.io
- Note the IP addresses returned.
- Create an A record for each IPv4 address (e.g.
- Create an AAAA record for each IPv6 address (e.g. use
Note: The ipfs.io gateway IP addresses won't change, so you can set them and forget them. If you use a custom gateway where you don't control the IP address and they could change you may need to re-check them periodically and update your DNS records if they do.
Visitors' browsers will send
your.domain in the Host header of their requests. The ipfs gateway will recognize
your.domain, look up the value of the DNS TXT for your domain, then serve the files in
/ipns/your.domain/ instead of
If you point
your.domain's A and AAAA record to the IP addresses 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 at
# Use CNAMEs
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.
However you will need to change the key for the TXT record from
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.