IPFS Docs

# Host a single-page website on IPFS

In this tutorial, we will host a simple one-page website on IPFS and link up a domain name. This is the first step is a series of tutorials to teach web developers on how to build websites and applications using IPFS.

# Using IPFS Companion

The IPFS Companion extension to the Chromium web browser included with your Pirate Box is an easy way to get up and running quickly with IPFS. You can open it from the Pirate Box Tools menu--> IPFS Control Panel or by the bookmark on the Chromium bookmarks toolbar. To follow this tutorial you need to be online and have completed the Pirate Box Setup Wizard.

# Add your site

We'll start by importing a simple one page website into IPFS using IPFS Companion. The website we'll be using as an example is incredibly simple. The purpose of it is to display random planet-related facts. Each time the page is refreshed, a new fact is displayed. The website is creatively called Random Planet Facts.

  1. Create a file called index.html and paste the following code into it and save:

    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Random Planet Facts</title>
    <meta
      name="description"
      content="Get a random fact about a planet in our solar system."
    />
    <meta name="author" content="The IPFS Docs team." />
    <style>
      body {
        margin: 15px auto;
        max-width: 650px;
        line-height: 1.2;
        font-family: sans-serif;
        font-size: 2em;
        color: #fff;
        background: #444;
      }
    </style>
  </head>
  <body onload="main()">
    <h1>Random Planet Facts</h1>
    <p id="output_p"></p>
    <script>
      function main() {
        const facts = [
          'Mars is home to the tallest mountain in our solar system.',
          'Only 18 out of 40 missions to Mars have been successful.',
          'Pieces of Mars have fallen to Earth.',
          'One year on Mars is 687 Earth days.',
          'The temperature on Mars ranges from -153 to 20 °C.',
          'One year on Mercury is about 88 Earth days.',
          'The surface temperature of Mercury ranges from -173 to 427°C.',
          'Mercury was first discovered in 14th century by Assyrian astronomers.',
          'Your weight on Mercury would be 38% of your weight on Earth.',
          'A day on the surface of Mercury lasts 176 Earth days.',
          'The surface temperature of Venus is about 462 °C.',
          'It takes Venus 225 days to orbit the sun.',
          'Venus was first discovered by 17th century Babylonian astronomers.',
          'Venus is nearly as big as the Earth with a diameter of 12,104 km.',
          "The Earth's rotation is gradually slowing.",
          'There is only one natural satellite of the planet Earth, the moon.',
          'Earth is the only planet in our solar system not named after a god.',
          'The Earth is the densest planet in the solar system.',
          'A year on Jupiter lasts around 4333 earth days.',
          'The surface temperature of Jupiter is around -108°C.',
          'Jupiter was first discovered by 7th or 8th century Babylonian astronomers.',
          'Jupiter has 4 rings.',
          'A day on Jupiter lasts 9 hours and 55 minutes.',
          'Saturn was first discovered by 8th century Assyrians.',
          'Saturn takes 10756 days to orbit the Sun.',
          'Saturn can be seen with the naked eye.',
          'Saturn is the flattest planet.',
          'Saturn is made mostly of hydrogen.',
          'Four spacecraft have visited Saturn.',
          'Uranus was discovered by William Herschel in 1781.',
          'A year on Uranus takes 30687 earth days.',
          'Uranus turns on its axis once every 17 hours, 14 minutes.',
          'With minimum atmospheric temperature of -224°C Uranus is nearly coldest planet in the solar system.',
          'Only one spacecraft has flown by Uranus, the Voyager 2.',
          'Neptune was discovered in 1846 by Urbain Le Verrier and Johann Galle.',
          'Neptune has 14 moons.',
          'The average temperatue of Neptune is about -201 °C.',
          'There is a 1:20 million scale model of the solar system in Sweden.',
          'The gap between the Earth and our moon is bigger than the diameters of all the planets combined.',
          "The first accurate calculation of the speed of light was using Jupiter's moons",
          "Jupiter's magnetic field is believed to be a result of rapidly spinning metallic hydrogen at the core, and is ~10x stronger than the Earth's.",
          'Venus spins backwards.',
          'Uranus spins sideways, relative to the ecliptic plane of the solar system.',
          'It is easier to reach Pluto or escape the solar system from Earth than being able to <i>land</i> on the Sun.'
        ]
        document.querySelector('#output_p').innerHTML =
          facts[Math.floor(Math.random() * facts.length)]
      }
    </script>
  </body>
</html>

  2. In IPFS Companion, go to the Files page.

  3. Click Add → File.

  4. Navigate to your index.html file and select Open.

    Choose a file window open in IPFS Companion.

  5. Click the triple dot menu on index.html and select Share link.

  6. Click Copy to copy the file's URL to your clipboard.

    Share files window in IPFS Companion.

  7. Open another browser tab and paste in the URL you just copied.

Your browser should load the website in a few moments! This can take up to a few minutes the first time. You can move onto the next section while the site is loading.

# Pinning files

IPFS nodes treat the data they store like a cache, meaning that there is no guarantee the data will continue to be stored. Pinning a file tells an IPFS node to treat the data as essential and not throw it away. You should pin any content you consider important to ensure that data is retained over the long term. IPFS Companion allows you to pin files straight from the Files tab.

IPFS Companion application showing the pinning option.

However, if you want your IPFS data to remain accessible when your local IPFS node goes offline, you might want to tell as many people as possible to access it, have other IPFS nodes pin it, or use other options like collaborative clusters and pinning services.

# Collaborative clusters

IPFS collaborative clusters are groups of IPFS nodes that collaboratively pin all content added to the IPFS Cluster by one or many trusted peers. You can learn more about collaborative clusters, including how to set up a cluster yourself, from cluster.ipfs.io (opens new window)

# Pinning services

An easy way to make sure important data is retained is to use a pinning service. These services run lots of IPFS nodes and will pin your data for you! This way, you don't have to run and maintain your own IPFS node. Check out the Persistence page for more information on pinning services. In this tutorial, we're going to use Pinata (opens new window) since it gives new users 1GB of storage for free, and has a very simple interface:

  1. Go to Pinata.cloud (opens new window) and sign up or log in.

  2. Click Pinata Upload.

  3. Select Upload File and click Browse.

  4. Navigate to your index.html file and click Open.

  5. Click Upload.

  6. Once the file has finished uploading, click Pin Explorer to view any files you have pinned.

  7. You should be able to see your index.html file pinned:

    The Pinata Pin Explorer screen showing the index.html pinned.

  8. Click the IPFS Hash of your index.html file to open your website through the Pinata gateway.

    Random planet fact website pinned using Pinata and displayed in Firefox

# Set up a domain

This section is completely optional.

If you have access to a domain name service like Namecheap, Google Domains, GoDaddy, or any other domain service, then you can follow along with these steps. If you don't have a domain name to assign, you can just read along this section. We will dive into using decentralized naming services like Ethereum Naming Service (ENS) in a later section.

We used Namecheap, but the process is very similar across all domain name services.

  1. Log into your domain name provider.

  2. Go to your domain management window and find the domain you want to assign to your website.

  3. Find where to change the Redirection Settings.

  4. In a new tab, open Pinata (opens new window), log in, and copy the IPFS Hash for your website.

  5. In your domain name providers Redirection Settings section, paste in the IPFS Hash link you just copied.

    Redirecting a source URL to an IPFS Hash link within Namecheap.

  6. Save your changes.

Domain name services are fairly slow to update. You should be able to go to your domain and see the website you pinned in a few hours.

Random planet facts site with the randomplanetfacts.xyz URL.

# Up next

This project was designed to get you up and running quickly, but there are many improvements we can make here.

You may have noticed that when visiting randomplanetfacts.xyz (opens new window), your browser redirects to gateway.pinata.cloud/ipfs/QmW7S5HR... (opens new window). This isn't great for the user's experience, and it can cause issues with security certificates and other website validation methods. Also, this website is incredibly simple. There are no images, external stylesheets, or javascript files. If you're interested in building a more complex site using IPFS and securing it properly, carry on with this tutorial series by hosting a multipage website on IPFS.

Help us improve this site!

Last Updated: 8/24/2021, 4:11:29 PM