Tutorial: Setting up an IPFS peer, part I
How to quickly (and inexpensively) spin up a cloud-based IPFS peer and start connecting to the distributed web
This post is the first in a series of step-by-step guides on “getting started with the Interplanetary File System (IPFS)”. In this post, we going to cover launching an Amazon AWS EC2 instance, installing IPFS and related technologies, initializing and running our IPFS peer node, and connecting to the distributed web. We’re going to assume you haven’t already used your free year of AWS access yet. If you have, or use AWS regularly, well then you probably don’t need the first part of this tutorial, and can just skip down to the part about getting IPFS set up. Otherwise, let’s create an account and spin up a (free) instance to get us started.
Getting started with EC2
Before we get going, you might be wondering “should I really be using a centralized cloud-server provider to spin up a decentralized IPFS peer?” The short answer is: “if it helps bootstrap the IPFS ecosystem, I say let’s do it!” The longer answer might be: well, the IPFS community is all about making the transition to a safer, faster, decentralized Internet at seamless as possible. This means you sometimes have to work within the incumbent system before you can completely ‘break free’. Ok, now back to your regular programing…
First, pop on over to aws.amazon.com/free/ and
Create a Free Account. When you hit
Continue, it’ll take you to a page to fill in your contact information. I setup a
Personal account. On the next page, you will need to enter your credit card information. We won’t be setting up anything beyond the free-tier services, but… be warned, you are giving up your credit card information and could be charged for something if you aren’t careful. If you start pinning popular files, you will get dinged for data transfer.
Update: After about 1 month of uptime on AWS, a personal peer node running 24/7 cost me about $8 in AWS fees…
Finally, you’ll need to do a phone verification. Just enter the code on the screen after answering the call, and Amazon will take care of the rest. Now you can select the
Basic (free) plan, and you’ll be directed to a page where you can complete the signup and
Sign In to the Console. Once logged in, you can go to your username drop-down (upper right of the page), select
My Account > Preferences (on the right) and enable
Receive Free Tier Usage Alerts and
Receive Billing Alerts, just to be on the safe side.
Next, we’ll create our basic free-tier AWS EC2 instance. Click on
Services > Compute > EC2. You’ll end up on a page listing the Amazon EC2 resources you are currently using. Right now, it’s probably just
1 Security Group. So let’s change that, and add an EC2 instsance by clicking on
Now you have some choice. AWS asks you to pick an Amazon machine image (AMI). These are basically virtual machine templates that come pre-installed with a (Linux) operating system. I’m going to go with the Ubuntu Server for this demo. By default, this will bring you to the
Instance Type page, where you can just stick with the default
t2.micro. Go ahead and click
Configure Instance Details. We’ll skip this first page (use defaults), and click on
Next: Add Storage. The free tier gives us up to 30 GB of EBS storage, so we might as well use it.
Next, skip over
Add Tags, and go straight to
Configure Security Group. By default,
SSH connections on port
22 are enabled from any source. This is probably fine, though restricting access to known IP addresses is probably a good idea. We’ll add some rules here (and maybe change the group name).
Review and Launch and then
Launch. This will bring up the dialog to create a key new pair. So select
create a new key pair, name it something useful like
ipfs, and download the
pem file (your browser might automatically append
.txt to the downloaded file name, so you’ll want to remove this before subsequent steps). Then click
Launch Instances. If you hadn’t setup billing alerts previously, you can do it now by clicking on the links.
While you wait for your instance to launch, you can
View Instances, or read up on how to connect to your Linux instance. For the rest of this session, I’m going to assume you have access to a command-line shell (Terminal). If not, the above link has some useful resources for connecting with other types of ssh clients. Unless otherwise stated, you’ll be entering (copy-paste) the following commands into your Terminal.
Connecting to your instance
First, change directories (
cd) to the location of the private key file that you created when you launched the instance (mine was in
Downloads). Next, use the
chmod command to make sure that your private key file isn’t publicly view-able.
chmod 400 ipfs.pem
ssh command to connect to your instance. You need to specify the private key (
.pem) file and use the following connection address:
user_name@public_dns_name. For example, if you used an Ubuntu AMI, the user name is
ubuntu. You can find the
Public DNS (IPv4) name on the
Description tab of your instance Dashboard.
Et voila, you have connected securely to your running AWS EC2 instance. Now let’s IPFS-ify it!
Put some IPFS in it
So first things first: let’s download the go-ipfs binary (
wget), unpack it (
tar xvfz), remove the downloaded archive (
rm), move it (
sudo mv) to a directory where our executable programs are located, and then remove (
rm -rf) the unpacked folder (since we no longer need it):
tar xvfz go-ipfs_v0.4.15_linux-amd64.tar.gz
sudo mv go-ipfs/ipfs /usr/local/bin
rm -rf go-ipfs
The next step is to setup (initialize) our IPFS repo. We do this by first specifying where we want to store our repo (in this case, in
/data/ipfs), and then we
init the whole thing. First, we’ll add our repo path to our
.bash_profile script and
source that (run the code contained in the file). Make sure you actually make the required directory (
mkdir), and take ownership of it (
chown) before trying to initialize the server (
echo 'export IPFS_PATH=/data/ipfs' >>~/.bash_profile
sudo mkdir -p $IPFS_PATH
sudo chown ubuntu:ubuntu $IPFS_PATH
ipfs init -p server
Ok, we’re almost there. Now let’s configure out repo a bit. We’ll increase our storage capacity (
Datastore.StorageMax), and if you want, enable the public gateway. But, you might want to skip this one if allowing people to access files through your gateway makes you nervous:
ipfs config Datastore.StorageMax 20GB
# uncomment if you want direct access to the instance's gateway
# ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080
Keeping things going
Cool. We’re now ready to start our IPFS daemon. But, since this is a cloud compute node, we don’t want to have to start and stop things ‘manually’. If our instance gets restarted, we’d like IPFS to start automatically. So let’s set that up using the
systemctl service. First, we’ll set up an
sudo bash -c 'cat >/lib/systemd/system/ipfs.service <<EOL
ExecStart=/usr/local/bin/ipfs daemon --enable-gc
And then enable our new service,
sudo systemctl daemon-reload
sudo systemctl enable ipfs.service
And start it, and check it out (a sanity check if you will):
sudo systemctl start ipfs
sudo systemctl status ipfs
You should see something like the following, along with the output from the
● ipfs.service - ipfs daemon
Loaded: loaded (/lib/systemd/system/ipfs.service; enabled; vendor preset: enabled)
Active: active (running) since Fri xxxx-xx-xx xx:xx:xx UTC; xx ago
Main PID: xxxx (ipfs)
└─1738 /usr/local/bin/ipfs daemon --enable-gc
You can also see that your fellow IPFS peers are connecting and routing through your newly configured node. If you run
ipfs swarm peers, you should (eventually) see a nice long list of connected peers.
We are officially connected to the dencentralized web.
Ok, so we’ve now created a new EC2 instance, installed IPFS on it, and started running our IPFS daemon. If you opened up your gateway, you should now be able to browse to its address in a browser, and ask for the docs directory:
http://ec2-xx-xxx-xxx-xx.us-xxxx-2.compute.amazonaws.com:8080/ipfs/QmS4ustL54uo8FzR9455qaxZwuMiUhyvMcX9Ba8nUH4uVv, or anything else accessible on the decentralized web.
There are lots of additional config options you can try, and port/security configurations you could use to protect your instance. You might also want to enable secure websockets on your instance (we’ll cover this in detail next week), or some of the other IPFS experimental features. In particular, stay tuned for next week’s post, where we’ll cover setting up a reverse proxy with NGINX, enabling a secure gateway, peer-to-peer (p2p) connections with browsers, and so much more!
Until then, why not check out some of our other stories, or sign up for our Textile Photos waitlist to see what we’re building with IPFS, or even drop us a line and tell us what cool distributed web projects you’re working on — we’d love to hear about it!