In this tutorial, we install IPFS and learn its basic commands.
Familiar with the command line and IPFS concepts.
There are 3 ways to install IPFS:
- from a prebuilt package
- from ipfs-update
- building from source
In this post, we install from a prebuilt package. Download the appropriate binary from the link above.
Unzip the package where you want to store the IPFS binary, and add the IPFS binary to your PATH.
Open your terminal and try the following to test your install works:
Note: For Windows users, I recommend Powershell over Command Prompt.
https://gist.github.com/da2d730111d6a22f57701af8b854bf72
That's It! You now have the IPFS installation on your machine.
Before we can use IPFS, we must initialize a local repository. This repository contains the settings and internal data for your user account. It also generates a peer identity key to sign any content you create cryptographically.
https://gist.github.com/df1445bf7973dbfb5c51345f17d6f60f
The init command outputs your peer identity key. This key is similar to an account number. The init command suggests the following command to try:
https://gist.github.com/364f5c9f896cc3887fc1c6f4cfacff92
You should see something like the below:
Hello and Welcome to IPFS!
██╗██████╗ ███████╗███████╗
██║██╔══██╗██╔════╝██╔════╝
██║██████╔╝█████╗ ███████╗
██║██╔═══╝ ██╔══╝ ╚════██║
██║██║ ██║ ███████║
╚═╝╚═╝ ╚═╝ ╚══════╝
If you see this, you have successfully installed
IPFS and are now interfacing with the ipfs merkledag!
-------------------------------------------------------
| Warning: |
| This is alpha software. use at your own discretion! |
| Much is missing or lacking polish. There are bugs. |
| Not yet secure. Read the security notes for more. |
-------------------------------------------------------
Check out some of the other files in this directory:
./about
./help
./quick-start <-- usage examples
./readme <-- this file
./security-notes
You can try the other files suggested by replacing readme in the last command.
It's important to know where your IPFS repository is located because this is where all your content is stored. The default location is an .ipfs folder in your home folder.
Note: The quick start guide from the readme gives a list of all commands to assist with getting started.
Navigate to a directory where you would like to create a file and try the following:
https://gist.github.com/d3e4ed6529189a20c2ff10cd47a8611f
Now let's create a file inside this folder.
https://gist.github.com/0d2749f90ef2b3a1095be6dceff0812b
The text file helloworld.txt contains "hello world 1". Next, add the file to IPFS.
https://gist.github.com/75cf020f96e4a9ec37a47eaa0395c364
You see the following output:
https://gist.github.com/da40a6ae225733c61808825463171547
The combination of letters and numbers is the hash that's associated with this text file. The hash is created based on the contents of the file. If you change the contents of the file, the hash changes, save this hash to access the file later on.
Without using IPFS, we can read the contents of the helloworld.txt file with the following command:
https://gist.github.com/67de774f07b05733e15a949451f2b395
We can read it through IPFS as well. Using the hash generated earlier, enter the following to return the contents of the file:
https://gist.github.com/f5dba7f969d19687e0c2227269844296
Let's see what happens if we change the text inside our helloworld.txt file.
https://gist.github.com/f7547303a9fc19da19aeeb529bd8251b
We changed the text to say "hello world 2" and when we added it to IPFS, we received a new hash. Using the cat command, we see that our helloworld.txt file was updated with the new text.
It's also possible to still read the "hello world 1" phrase that we had earlier.
https://gist.github.com/1e484ad638ce9d0b09e9a686c90ba87d
Using the first hash, IPFS outputs "hello world 1". We read the contents of the hash rather than the contents of the file. Reading the helloworld.txt file we see that the contents haven't changed.
We can revert to the "hello world 1" text if we wish.
https://gist.github.com/154866c7928c7b1a00a99abab57bf7ce
As mentioned earlier, content on your node stays there for a short period. Pinning allows you to tell IPFS what you want to keep for an extended period.
Using the file, we created earlier, use the command below to pin it:
https://gist.github.com/75f66ba8bcc9b5d9a310d3883e8b1fbf
Once pinned, it stays on our node. Let's see what happens when we try to clean our node of all hosted files (garbage collection):
https://gist.github.com/4804caa5ec49eb63173a77e37bffb04e
We couldn't collect the file couldn't because we pinned to our node.
https://gist.github.com/23802d44c2c6bc62e3e2ce3aa6b3dc12
The first command removes the pin. When we garbage collect, it's removed from our node. The file is still available in our local directory stored on our computer, but we are no longer hosting it on the node.
So far we've worked with IPFS locally. Now we're ready to try things online. Open another terminal and run the daemon command.
https://gist.github.com/33b5e0a413dab9c3814fbbfc944d93b8
The daemon allows us to interact with the IPFS network through localhost in our browser. Switch back to the other terminal to take a look at our peers.
https://gist.github.com/73279c1ca3879538848db8bbd1f44b7e
This command results in a bunch of addresses flashing across the terminal. We opened the swarm component that allows us to listen and maintain connections with other peers on the network. The peers command allows us to see every peer that has an open connection.
Note: If you ever get an error message saying "API not found," run the daemon command and continue where you left off. To ensure that IPFS runs correctly it is suggested to run the daemon command every time you use IPFS, even locally.
We've successfully connected to the IPFS network and from here can get content from other nodes if we know the hash of the content.
If we know the hash of a file and want to save it on our computer we can do the following:
https://gist.github.com/2eca5fd897a7a14f4b1b0dec937a84ed
We can also view a file directly in our browser using the path http://127.0.0.1:8080/ipfs/Qmdh9Sk33zbLgPCPsadcSrvaJt4YUifP3njYbZT9W7B9zG.
You should see a picture of a dog. If you know the hash of another file, just replace the hash!
Now that we've connected our node to the network we can use the IPFS Web Console.
In the console, we can:
- check the status of your node
- upload files to IPFS
- explore files
- see your peers
- adjust settings for your node
The web console is the best tool for managing IPFS node.
We've covered the basics of working with IPFS. Here is a summary of all the commands covered, and a handful of other useful ones:
ipfs add name-of-file: Adds a file to IPFS.ipfs cat hash-of-file: Shows the contents of the file.ipfs pin add hash-of-file: Pin file to local IPFS storage.ipfs pin rm hash-of-file: Removes pinned file from local IPFS storage.ipfs repo gc: Removes files from IPFS storage.ipfs daemon: Starts an online connection to the network.ipfs swarm peers: List peers with open connections.ipfs commands: Lists all commands.ipfs id: Tells you your id as well as other node id information.ipfs version: The version of IPFS you are running.ipfs help: Provides you with help information.
Note: Try any command in the following format: ipfs base-command , and the terminal displays the usage of that command.