How to Save a File on IPFS — A 7-Step Primer
Store files permanently on the Inter-Planetary File System (“IPFS”), and learn how to do so quickly and easily in this guide.
The Inter-Planetary File System, or “IPFS”, is one of the most amazing technologies I’ve ever seen.
The IPFS lets you store your files permanently by backing them up on computers around the world. And it lets you download your files faster. Let me explain.
Let’s say your company creates a critical 1-hour video clip daily, which millions of consumers watch daily and retroactively. This would be an expensive endeavor! You’ll need to buy a lot of bandwidth and storage space.
And if your videos are truly critical, then they should be accessible no matter what. However, with today’s HTTP protocol, the videos are accessible only so long as your servers are running and consumers can retrieve the data amidst busy traffic.
But what if the video files were distributed throughout the world so that they could never be lost? What if you could retrieve pieces of the video files quickly from your neighbors’ computers instead of traveling to a server across the world? What if you could also update, rename, and set permissions on these files while they sit remotely, stored throughout the universe?
Well then you would have a decentralized, more permanent internet. One where links never return 404 errors, and one where we’re not reliant on Amazon, Google, Facebook, and Apple’s servers. It’s like the HTTP web + Git + BitTorrent.
This is the future promised by the Inter-Planetary File System.
How do I save a file to IPFS?
The way you interact with IPFS today is through a command-line interface. This can be a new experience to non-programmers, so I’ve written this step-by-step guide to upload your first file to the IPFS¹.
Step 1: Download and Install IPFS for your Platform
This one is easy, just follow this link to IPFS’ website and download.
Step 2: Move the Executable File to its Proper Location
You just downloaded a compressed folder. Now we must extract the contents, and place the ipfs file in the $PATH / %PATH% (Read this on PATH if confused). Instructions begin to differ between Mac/Linux and Windows operating systems:
For Mac/Linx:
After downloading, unpack the archived folder, and move the ipfs file somewhere in your $PATH. To do this via Terminal:
sudo mv ipfs /usr/local/bin/ipfsFor Windows:
After downloading, unzip the archive, and then cut ipfs.exe and paste somewhere in your %PATH%. You can also complete this via Command Prompt:
[Win + "cmd" -> right-click -> Run as Administrator]
C:\Users\yourName\Downloads>move .\go-ipfs\ipfs.exe C:\WindowsStep 3: Initialize IPFS
Great job so far! At this point you must open your command-line interface to continue. On a Mac, search for terminal, for Windows, search for cmd.
Now, confirm that you have properly moved the executable file by typing ipfs and hitting Return. You should see the following:
USAGE
ipfs - Global p2p merkle-dag filesystem.
...Everything is installed properly, so it is time to init your IPFS repository². Type: ipfs init and hit Return. You will see something similar to this:
$ ipfs init
initializing ipfs node at /Users/yourName/.ipfs
generating 2048-bit RSA keypair...done
peer identity: Qmcpo2iLBikrdf1d6QU6vXuNb6P7hwrbNPW9kLAH8eG67z
to get started, enter:
ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/readmeGo ahead and follow the instructions: copy and paste ipfs cat /ipfs/QmY...bdG/readme and you should see something like the following³.
Hello and Welcome to IPFS!
██╗██████╗ ███████╗███████╗
██║██╔══██╗██╔════╝██╔════╝
██║██████╔╝█████╗ ███████╗
██║██╔═══╝ ██╔══╝ ╚════██║
██║██║ ██║ ███████║
╚═╝╚═╝ ╚═╝ ╚══════╝
If you're seeing this, you have successfully installed
IPFS and are now interfacing with the ipfs merkledag!Step 4: Add a File to IPFS
Now we’re ready to add our first file to IPFS! 🎉
First, in the terminal, you want to "change directories” to get to the folder where your files reside. To change directories, type cd c:/yourPathHere (video tutorial here). I’m going to grab a folder called rare in my Pictures folder.
I’m going to add to IPFS the folder storing the picture to the left (rare.jpg) and another sample.
See how easy this is below:
$ ipfs add rare -r
added QmUbTW9iDRz4XgbHc62viUDSM76i1n52frG8HqqyarfMQk rare/XXX.jpg
added QmRuzPpc1tjJ5TbhG7B2Ato8LtaY2DK2Y5DMWWb29cqFF5 rare/rare.jpg
added QmdNMBVqQJ9baQDAJMUwci8LzVK2a52cTLEHoinaKFEdFY rareWhat you see above is a pathway (i.e. a link) to the parent folder rare, and direct links to the child objects.
Step 5: Pin your File to IPFS
Next, we’re going to pin the files we added to IPFS to our local storage. Presumably these files already exist on our machine, and by pinning the file, other nodes on the IPFS network know they can access the file from our machine. Below I pin the rare directory:
$ ipfs pin add QmdNMBVqQJ9baQDAJMUwci8LzVK2a52cTLEHoinaKFEdFY
pinned QmdNMBVqQJ9baQDAJMUwci8LzVK2a52cTLEHoinaKFEdFY recursivelyStep 6: Connect your IPFS Machine to the Network
In this next step, we will introduce your machine to the IPFS network. This allows other participants on the network to listen to your machine, to retrieve files from your machine, and for you to access files on others’ machines⁴.
Type the following to connect to the network:
$ ipfs daemon
Initializing daemon...Open another terminal (or Command Prompt), and take a look at who is connecting to your machine:
$ ipfs swarm peersProtocol Labs, the company that maintains IPFS, has a number of bootstrapping nodes that are actively looking for new content placed on the network.
Further, Protocol Labs maintains a HTTP -> IPFS gateway, and you can access any one of your files from their website, where they have mounted the IPFS system on their HTTP URL: https://ipfs.io/ipfs/[yourHash].
Check out my file above, fully loaded on IPFS: https://ipfs.io/ipfs/QmRuzPpc1tjJ5TbhG7B2Ato8LtaY2DK2Y5DMWWb29cqFF5
Step 7: Don’t Forget to Close the Daemon
Last but not least, make sure you disconnect from the network when you are done. Go back to the terminal where the daemon is running, and hit: CTRL + C to stop the process.
I hope you enjoyed this 7-step primer on adding a file to the IPFS!
Please make sure to 👏 if you enjoyed this post. Feel free to reach me on Twitter or GitHub @JohnZettler or learn more about my background here: johnzettler.com.
Editorial thank you’s: Tommy Nicholas, Kevin Trinh, Matthew Russo
[1] Note that my machine is a Windows 10, x64, operating system, and I use Cygwin to replicate a Unix-like environment on my machine. To Windows users — feel free to use cmd.exe — this also works.
[2] This is likely a new concept for those new to Git. Think of this like a virtual storage folder that can track both files on your machine and their version history.
[3] Note that the hash (i.e. the address) will be different in your terminal’s output than the example above. Use the one that your terminal spits out.
[4] Recall that accessing any network involves security risks, and that IPFS is in Alpha. Access the IPFS at your own risk on your own volition.
