IPFS: A Basic Guide To Store And Access Your Data

Introduction:

So you probably already know about IPFS(Interplanetary File system) and how awesome it is. But, if not, it’s a peer-to-peer distributed file system used to store and access files, websites, applications, etc. The unique thing about it is that your data is not just stored on servers but stored in various computers around the world in various chunks. IPFS seems to be a very interesting concept to learn about, but, a bit scary to actually start using. Despite that, using IPFS is very simple. Anyone who even has slight know-how of the command line can use it.
So here we will be implementing IPFS first in the command line and then using the JavaScript package ipfs-core.

IPFS Command Line

Installation:

For this tutorial, we will be implementing IPFS using Ubuntu.

To implement IPFS on the command line you need go-ipfs. You can either download go-ipfs Or you can just execute the following command in your terminal.

$ wget https://dist.ipfs.io/go-ipfs/v0.7.0/go-ipfs_v0.7.0_linux-amd64.tar.gz

At the time of writing this, the latest version is 0.7.0. If there is a newer version you can download that instead.

After downloading go-ipfs you will have a .gz file, you will need to extract the file. You can do that easily by opening the terminal in the directory where the .gz file is located and execute it using the following command.

$ tar -xvzf go-ipfs_v0.7.0_linux-amd64.tar.gz

This will extract the go-ipfs folder. Now to install IPFS first traverse into the folder.

$ cd go-ipfs

Inside you will find an install.sh file, you just need to execute it using sudo bash.

$ sudo bash install.sh

With this, you have installed IPFS successfully. You verify this through the following command.

$ ipfs --version

> ipfs version 0.7.0

After this, you need to do one last thing before you can start using IPFS properly and that is initializing your ipfs repository. IPFS stores all its configuration and internal files in this directory and if you are using it for the first time you will need to initialize that first.

You can do that simply, by using

$ ipfs init

With this, your repository has been initialized and the Merkle-DAG hash of your repository has also been generated. In case you are wondering what a Merkle-DAG is, it stands for Merkle Direct Acyclic Graph. DAG is a graph consisting of various nodes connected to each other with direction and Merkle-DAG is the root hash of all the nodes. Since IPFS breaks our files into different chunks, it uses DAG as a manner of storing the file in a secured way such that retrieving it would be easily possible.

You can use this generated hash to view the contents of the ipfs readme file and quickstart file present in the directory. You can read them using the "ipfs cat" command.

$ ipfs cat /ipfs/<your directory hash>/readme

$ ipfs cat /ipfs/<your directory hash>/quick-start

You have now successfully installed and set up ipfs in your command line. Now you are ready to store and retrieve files from the IPFS network.

Adding and Reading Files:

Now let's begin using IPFS by creating a Hello_World.txt file, adding it to the network, and reading its content. You can upload files to IPFS by using the "ipfs add" command. Execute the following lines.

$ echo “Hello World” >Hello.txt

$ ipfs add Hello.txt

You have now successfully uploaded your Hello.txt file to the IPFS network and have been given a unique Merkle-DAG of your file which you can use to access data and give it to your friends so they too can get your file.
You can read your file using the "ipfs cat" command

$ ipfs cat <your Merkle DAG>

This outputs the content of the file which in this case is “Hello World”. Similarly, go to a different directory and execute

$ ipfs get <your Merkle DAG>

The "ipfs get" command can retrieve any file from the IPFS, given it is available. You now have the Hello_World file having its name as the MerkDAG of the file.

Now let’s try something, here is the hash to my desktop wallpaper QmYA2fn8cMbVWo4v95RwcwJVyQsNtnEwHerfWR8UNtEwoE

Try retrieving it using "ipfs get", you would probably be getting the following message.

So far what we have been doing is just creating our files and notifying our ipfs client where to find our file. For us, that is simple since the file in question is located on our local storage, hence, fetching that is easy. However, for other users that won’t be possible since we haven't connected our client to the IPFS network and notified everyone where our files are located. The same applies to us, the reason we can't find this file is that we are not connected to the ipfs network and our ipfs can only search our local storage where the file is not available. To connect to the ipfs network we need to start a daemon process which we can do with the following command.

$ ipfs daemon

You will see the following messages.

Once its daemon is ready let's try fetching the file which I was trying to share.

$ ipfs get QmYA2fn8cMbVWo4v95RwcwJVyQsNtnEwHerfWR8UNtEwoE

This may take some time depending upon your geographical distance from the hosted file, but eventually, you will be able to get the file. As mentioned above it is my desktop's wallpaper so feel free to use it as you wish.

That concludes our tutorial on the basic usage of IPFS for adding and fetching files using the command line. You can simply enter "ipfs" on the command line to view all its commands with descriptions. Now let’s try to do the same with the IPFS JS package ‘ipfs-core’.

IPFS-JS Library:

If you are a developer you will most probably prefer doing all the above tasks through your javascript code rather than the command line. So for that, we have npm package called "ipfs-core". You can install that using the following command.

$ npm install ipfs-core

This package requires a node version of 12.0.0 or higher. If you attempt to use it with an older version you will be able to install it but while using it, errors may occur.

Let’s start by connecting to the ipfs network. First, create an ipfs instance for us to interact with and get its version.

const IPFS = require('ipfs-core')
const ipfs = await IPFS.create()
const version = await ipfs.version()
console.log(version)

Now with this ipfs instance, we can execute all the command line(add, cat, view) functionalities. Let's start with adding an ipfs Hello World file.

const IPFS = require('ipfs-core')

async function main(){
 const ipfs = await IPFS.create()
 const fileAdded = await ipfs.add({
   path: './Hello_World.txt',
   content: 'Hello'
 })
 
 console.log('Added file:', fileAdded.path)
}

This will simply create a file named Hello_World.txt with Hello in its content.

However, this way we can only insert text files to the IPFS, what if you want to upload an image or a video? For that, we need some help from the js package ‘fs’.

const IPFS = require('ipfs-core')
const fs = require('fs')
 
async function main(){
 const ipfs = await IPFS.create()
 
 fs.readFile('<Your File Path>', async function(err, data) {
   console.log(data)
 
   const fileAdded = await ipfs.add({
     path: '<path of the file you want on the IPFS>',
     content: data
   })
 
 console.log('Added file:', fileAdded.path)
});
}

You can always view the files you are uploading using their Merkle-DAG in the "ipfs get" command or you can also view by visiting the ipfs.io.

You can also do that by using ‘ipfs-core’. The following code gets the content from our uploaded file.

const IPFS = require('ipfs-core')
 
async function main(){
const ipfs = await IPFS.create()
 
 
 const chunks = []
 for await (const chunk of ipfs.cat('QmVZdicceMroeHLYiVvCc2CkPzrR5uoHF4Ks9uFhSyhX8z/Hello_World.txt')) {
     chunks.push(chunk)
 }
 
 console.log('file contents:', chunks.join())
}

And that concludes our tutorial for implementing IPFS using the JS library.

Conclusion:

And so with that, we have covered how to add, view, and retrieve files using IPFS. As a basic user, this is all that you need but there are deeper concepts in IPFS worth exploring such as Pinning, IPNS, and IPFS Buckets. We shall explore these concepts in detail in the future where I will make part 2 explaining how to make IPFS buckets.

December 18, 2020