IPFS Getting Started Guide
Want to get started using IPFS, but not sure where to begin? This guide walks you through everything you need to know to use IPFS on Filebase.

What is IPFS?

Interplanetary File System, also known as IPFS, is a decentralized peer-to-peer protocol for storing and retrieving files or websites.
IPFS is similar to HTTP, a protocol that is at the heart of how we use and create content on the internet currently. IPFS is relatively new and has a wide range of different attributes and benefits in comparison to HTTP.
Note: HTTP in this context refers to both HTTP and HTTPS. HTTPS should be used for all production environments for the most security and reliability of the content.
To bridge the gap between the two protocols, IPFS HTTP gateways combine the two protocols, allowing you to use and build with IPFS by accessing the IPFS network through HTTP requests.

HTTP and The Client-Server Model

Traditionally, when you access a webpage there are multiple protocols working together to deliver this website to you. First, the DNS protocol finds the IP address of the server that is tied to the domain name. Then, HTTP is used to request the website from the host server. This workflow is referred to as the client-server model.
While the client-server model is at the forefront of how we interact with and use the internet today, this model is centralized by design and therefore comes with risks such as unreliability, lack of resilience, and single points of failure. The client-server model puts all responsibility on the host server to ensure that the website is constantly available and accessible. If the host server is down due to an outage, disaster, or hardware failure, the website becomes unreachable and inaccessible.
Most notably, the HTTP protocol only sends your request for the website to the host server and doesn’t send your request to other servers that might be able to respond if the host server is down. This is a fundamental difference between HTTP and IPFS.

What About Centralized Cloud Providers?

Another model for website and file hosting or storage is to use cloud providers, like AWS or Google Cloud. This is a common workflow for many applications, websites, and platforms where cloud providers create redundancy and high availability by deploying these assets over multiple servers through high-level abstractions such as CDNs or storage services. Typically, though, these servers are all located in one geographical location, most of the time within the same server rack or row. This means that while there might be more redundancy on the protocol layer, there isn’t redundancy for data center-wide outages, disasters, or human error like a cable being disconnected by accident.
The cloud provider solutions are proprietary to each cloud provider, meaning they are not standardized, open-source, or interoperable due to these solutions being deployed at the hardware or software layers instead of on the protocol layer. This creates a hard vendor lock-in that can trap customers into staying with one provider, even if it isn’t benefiting them as much as another provider could.
Another problem with big cloud providers is that since each cloud provider has such a large market concentration, outages or disasters often have a detrimental effect when something happens like a hardware failure, fire, or even a human error. Outages of this size often affect thousands of websites, services, and platforms, which can bring down even more services if they rely on any of the websites brought down in the outage.

The Peer-To-Peer Solution

IPFS is a peer-to-peer network protocol, meaning instead of each client is connected to a host server like in the client-server model, each client (also referred to as a peer or node) is connected to every other peer to allow it to act as both the client and the server simultaneously. With this configuration, any peer can serve any requested file or website and be a productive member of the network to provide high availability, reliability, and resiliency to network outages or disruptions. With IPFS, peers are able to pool their resources such as storage space or internet bandwidth to ensure that files are always available, resilient to outages, and most importantly, decentralized.

How does IPFS work?

IPFS is unique from other decentralized storage networks because it offers additional features and attributes such as content addressing, directed acyclic graphics (DAGs), and distributed hash tables (DHTs).

Unique Data Identification via Content Addressing

Data stored on IPFS is located through its content address rather than its physical location. When data is stored on IPFS, it is stored in a series of encrypted pieces, with each piece having its own unique content identifier or hash. This hash serves as an identifier and links the piece to all the other pieces of that data.
Identifying an object, such as an object or a node, by the value of its hash is referred to as content addressing. The hash identifier is known as the Content Identifier or CID. When objects are uploaded to an IPFS bucket on Filebase, the IPFS CID is listed in the object’s metadata for easy reference in any tool or application, or for use with an IPFS gateway.

Content Linking via Directed Acyclic Graphs (DAGs)

Directed Acyclic Graphs are a hierarchical data structure. A graph is a way to display objects and the relationship between them. A directed graph is when a graph’s edges have direction, as depicted in the photo above. An acyclic graph is a graph where the edges have definitive ends and do not create a loop to other objects. Think of a family tree that shows ancestors and their relationship to one another. This is a good example of a Directed Acyclic Graph.
In this context, an object in a graph is referred to as a node and an edge refers to the relation between the objects in a graph.
IPFS uses Merkle DAGS, where each node has a unique identifier that is the result of hashing the node’s contents. Merkle DAGs are a form of self-verified data structures.

Content Discovery through Distributed Hash Tables (DHTs)

A distributed hash table (DHT) is a distributed system for mapping keys to their associated values. DHTs are databases of keys and values that are split across all the peers on a distributed network. To locate content, you ask a peer on the network, which will return a DHT that tells you which peers are storing which blocks of content that make up the data object you’re requesting.

Content Addressing vs. Location Addressing

Location addressing is used by client-server models to address content based on its location on the internet, typically through IP addresses. Location addresses have three parts, which are combined into a URL. These parts are:
  • Scheme: This refers to the protocol being used to serve the address, which typically is HTTPS.
  • Hostname: This refers to the domain name mapped to the IP address of the server, such as google.com
  • Path: This refers to the location of the file on the server, such as /assets/images/image.png.
Altogether, a URL typically looks like this:
Location addressing can cause issues with serving content if the URL changes in any way, such as if the file name changes or the file path gets adjusted. Sometimes, the server may not even be hosting the requested file anymore, and you’re brought to a broken webpage or image.
IPFS uses content addressing, since a file can be hosted simultaneously across different IPFS peers, trying to identify it by one location can be counterintuitive.
Content addressing is when a file stored on a peer-to-peer network is addressed by the cryptographic hash of the file’s contents. In IPFS, this cryptographic hash is known as the content identifier or CID.

What is an IPFS CID?

A CID is a string of numbers and letters unique to the cryptographic hash of the file or folder’s contents.
If a file is uploaded multiple times to IPFS, if the content of that file has not changed, it will return the same CID each time it has been uploaded.
Any change to the file’s contents at all will provide a different CID when uploaded. This assures that files uploaded to IPFS are immutable since any changes will produce a new, unique content identifier.
A single CID can represent either a single file or a folder of files, like a folder containing the files for a static website.

CID Formats

There are currently two different versions of IPFS CIDs - version 0 (0v) and version 1 (v1).

Version 0 (v0)

CIDv0 CIDs are the first format of IPFS CIDs that was part of the initial IPFS design. This version of the IPFS CID uses a base 58-encoded multi-hash to create the content identifier value. This method is simple but isn’t as versatile as the newest CID version, CIDv1. CIDv0 is still the default version for a wide variety of IPFS applications and operations, and it is recommended that you support CIDv0 in any development environment.
CIDv0 CIDs are 46 characters long and always start with the characters “Qm”.

Version 1 (v1)

CIDv1 aims to provide forward compatibility and support different formats that can be used with future versions of the IPFS CID. CIDv1 CIDs include:
  • A multi-base prefix that specifies the encoding method and format used for the rest of the CID.
  • A CID version identifier that specifies the version of the CID.
  • A multi-codec identifier that indicates the format of the content that the CID aims to identify. This helps software and programs interpret the content once the content has been fetched from an IPFS node.
The first few bytes of a CIDv1 CID can be used to interpret the remainder of the CID and provide information about how to decode the content once it has been fetched from IPFS.

When To Use CIDv0 vs CIDV1

Currently, new projects are advised to use CIDv1 in their development since this allows the project to be future-proofed, and IPFS plans to set the default CID version to CIDv1 as the new default in the future. CIDv1 CIDs are also safe to use in browser contexts, such as through IPFS subdomain gateways.

CID Conversion

When a CIDv0 is accessed with a traditional gateway, the domain will return an HTTP 301 redirect to a subdomain, converting the CIDv0 CID to CIDv1 CID.
For example, opening a CIDv0 resource using a traditional gateway at:
returns a redirect to a CIDv1 representation at:

How are CIDs used?

Once a file or folder is uploaded to IPFS and a CID is returned, that CID can be used to access the stored data through an IPFS gateway. All data uploaded to IPFS is public by default since all you need to access it is associated CID. There are no permissions, user accounts, or other security settings tied to IPFS CIDs.

Native IPFS URLs

Applications that natively support IPFS content addressing can refer to content stored on IPFS in the format:
ipfs://{CID}/{optional path to resource}
This format doesn’t work for applications or tools that rely on HTTP, such as Curl or Wget. For these tools, you need to use an IPFS gateway.

IPFS HTTP Gateways

IPFS HTTP gateways use the HTTP protocol to serve content hosted on the IPFS network, bridging the gap between the two different protocols. This means you can access content on IPFS through its IPFS CID in situations such as code snippets or applications that support HTTP, which most do.
Gateways are used to provide workarounds for applications that don’t natively support IPFS and can also be used as a sharing link for the data. An IPFS gateway can be local, private, or public, and uses the IPFS CID to provide a URL link to the content for access to the stored content.
Simply put, a gateway is an IPFS peer that accepts HTTP requests for IPFS CIDs.
The IPFS HTTP gateway format follows the structure:

The Filebase public IPFS gateway is:

Note: The Filebase Public IPFS Gateway has an effective rate limit of 200 RPM (requests per minute).
All content stored on IPFS through Filebase can be accessed through the Filebase gateway with faster response times than accessing the content through any other gateway. This is because the Filebase gateway peers with our IPFS nodes. The Filebase gateway also peers with the IPFS gateways of other pinning services.
Any gateway is capable of serving any IPFS CID, and accessing the same CID through multiple gateways will produce the same result.
For example, the following IPFS gateway URLs both lead to the same file:
Gateways can also serve the CID of a folder instead of just a single file. In this scenario, it will return a file directory tree that contains the files located in the folder.
For example, the following IPFS gateway URL leads to a folder directory of files:
Gateways can also be used to serve static websites. The following URL leads to a static webpage, hosted on IPFS using a folder containing a static HTML file and image files:

Public IPFS Gateways vs Private IPFS Gateways

Public gateways allow anyone to use HTTP to retrieve CIDs from the IPFS network. Filebase offers a public IPFS gateway with the following address:
There are two forms of private IPFS gateways: dedicated and self-hosted.
Dedicated gateways are offered by IPFS pinning services that allow you to access the CIDs pinned on IPFS through the pinning service through your own private dedicated gateway. Dedicated gateways are typically not limited to traditional rate limits that public gateways are.
Self-hosted gateways refer to an IPFS node that you host yourself, either in the cloud or on your local machine, that is configured to act as an IPFS gateway. Self-hosted gateways are not limited to rate limits either, but require an IPFS to be running and managed by you for functionality. Many users choose an IPFS pinning service that offers dedicated gateways so they can avoid hosting and maintaining IPFS nodes themselves.

IPFS HTTP Gateway Process

When a request for a CID is initiated using an IPFS HTTP gateway, the following steps occur:
  1. 1.
    The gateway checks if the CID has been cached locally before it attempts to retrieve it from the IPFS network. The cache can either be the local HTTP cache, or the cache of the IPFS gateway node.
  2. 2.
    If the CID hasn’t been cached, the CID will need to be retrieved from the IPFS network.
  3. 3.
    The IPFS peer will first ask its direct peers if any of them are hosting the requested CID, then it will query the DHT to find peer IDs and network addresses of peers that are currently hosting or pinning the requested CID.
  4. 4.
    The IPFS gateway node will connect to one of the peers with the CID, fetch the CID’s content, then relay the response to the client that requested the CID.

IPFS Pinning

Through content addressing and content identifiers, any IPFS peer can retrieve any given CID as long as the file is being served by at least one peer on the network. For example, if you request a CID from an IPFS peer and that peer is not hosting the file, it will search the entire IPFS network for the peer that has the file. Once it finds the peer, it will fetch the file associated with the CID and return it back to you.
To assure that at least one peer is hosting the file, IPFS offers a feature known as pinning. IPFS pinning refers to the process of specifying data to be retained and persist on one or more IPFS nodes. Pinning assures that data is accessible indefinitely, and will not be removed during the IPFS garbage collection process.
When files and data are stored on the IPFS network, nodes on the network cache the files that they download and keep those files available for other nodes on the network. Since storage on these nodes is finite, the cache for each node must be cleared periodically to make room for new files to be cached and made available. The process of clearing the cache for IPFS nodes is referred to as the IPFS garbage collection process.

Understanding the Garbage Collection Process

When files and data are stored on the IPFS network, nodes on the network cache the files that they download and keep those files available for other nodes on the network. Since storage on these nodes is finite, the cache for each node must be cleared periodically to make room for new files to be cached and made available. The process of clearing the cache for IPFS nodes is referred to as the IPFS garbage collection process.
Garbage collection is an automatic process that is used to manage resources, such as IPFS node disk space. The process is designed to remove cached data that it thinks is no longer needed, though if your IPFS CID refers to a file that is vital to your workflow or environment, having this file removed can be detrimental. So how do you prevent your file from being removed during this process?
To protect data from the garbage collection process, data must be pinned on the IPFS network. This ensures that data is retained indefinitely and is always accessible. Pinning is useful for a variety of workflows, such as accessing data files from around the world without managing sharing permissions. All data uploaded to IPFS is public by default since all you need to access it is the file’s CID. There are no permissions, user accounts, or other security settings tied to IPFS CIDs.
One of the most popular workflows utilizing IPFS pinning right now are NFT collections. These collections have a variety of files involved, including NFT image files and their associated metadata files. If these files aren’t pinned on IPFS and they get removed by the IPFS garbage collection process, this can result in an “NFT Rug Pull”, which means that the NFT ceases to exist, and is no longer accessible or transferable.

The Filebase IPFS Pinning Service

Filebase offers an IPFS pinning service, where all files uploaded to a Filebase IPFS bucket are automatically pinned on 3 different IPFS nodes within the Filebase infrastructure. This ensures 3x redundancy for all IPFS pinned files on the Filebase infrastructure for high availability, resiliency, and reliability.
Some pinning service providers don’t publish provider records to the IPFS DHT, or Distributed Hash Table. The DHT is responsible for keeping a distributed system that maps keys to values and maps the CID that a user requests with the peer that is hosting that content. The DHT is essentially a large table storing CIDs with their associated storage peer. Filebase publishes our provider records to the IPFS DHT for the best performance and CID retrieval time when requested.

Signing up for Filebase

Filebase uses a web-based console that can be found at https://filebase.com.
Existing accounts can go directly to https://console.filebase.com.
  1. 1.
    To sign up for a Filebase account, navigate to https://filebase.com. To make a new account, click the ‘Try for Free’ button in the top right corner of the webpage.
2. Next, fill out the fields of the form, including an email address and password, and agree to the Filebase terms to create your account.
Note: Temporary email addresses cannot be used to create a Filebase account.
3. You will receive an email with confirmation instructions. Click the link included in the email to confirm your account and finish the registration process.

How To Create An IPFS Bucket

Simply navigate to your Dashboard Console, create a new bucket and choose the IPFS option.

How To Pin New Data on IPFS With Filebase

Files uploaded to an IPFS bucket on Filebase are automatically pinned to IPFS and stored with 3x replication across the Filebase infrastructure by default, at no extra cost to you. This means your data is accessible and reliable in the event of a disaster or outage, and won't be affected by the IPFS garbage collection process.

Uploading a File to IPFS Through The Filebase Web Dashboard

  1. 1.
    Start by clicking on the ‘Buckets’ option from the menu to open the Buckets dashboard.
2. Select your IPFS Bucket.
3. After clicking on the bucket name, you will see any previously uploaded files. To upload another file, select 'Upload', then select 'File' from the options.
4. Select the file you want to upload to the IPFS.
5. Once uploaded, you will be able to view and copy the IPFS CID from the 'CID' category, as seen below.

Uploading a Folder to IPFS Through The Filebase Web Console

  1. 1.
    Start by clicking on the ‘Buckets’ option from the menu to open the Buckets dashboard.
2. Select your IPFS Bucket.
3. After clicking on the bucket name, you will see any previously uploaded files. To upload another file, select 'Upload', then select 'Folder' from the options.
4. Select the folder you'd like to upload to IPFS.
5. Once uploaded, the folder will look similar to IPFS individual files.
6. Copy the IPFS CID for your folder, then navigate to https://ipfs.filebase.io/ipfs/[CID]. The contents of your folder will be listed.

Uploading a File to IPFS Using the S3-Compatible API

If you're using the S3 compatible API, the CID will be returned in the response of a PutObject call.
For example, if we run the following AWS CLI command:
aws --endpoint https://s3.filebase.com s3 cp test-images/7FIMFhlMf6A.jpg s3://ipfs-test --debug
For more information on AWS CLI, see here.
The response is shown below. For convenience, we've highlighted the respective response header:
You can also call the HeadObject API to fetch the CID at any time as well:
aws --endpoint https://s3.filebase.com s3api head-object --bucket ipfs-test --key 7FIMFhlMf6A.jpg

Uploading a Folder to IPFS Through the S3-Compatible API

A CAR file is a type of compressed archive file that contains multiple files, similar to a ZIP file. CAR files are used by the FileCoin and IPFS networks, which utilize the metadata fields to include the IPFS CIDs of each file within the archive.
Filebase supports uploading CAR files to IPFS using the S3-compatible API through the PutObject or MultipartUpload methods.
For information on creating CAR files, check out our guide here.
When you upload a CAR file, you can pass an S3 metadata header of x-amz-meta-import: car along with the request. Filebase will then import the file as a CAR, and return the resulting CID.
Below is an example using the AWS CLI, which adds the x-amz-meta prefix automatically:
aws --endpoint https://s3.filebase.com s3 cp pictures.car s3://ipfs-test --debug --metadata 'import=car'
With the specified –debug flag, the response headers are shown, which reveal the CID:
2022-06-14 19:51:41,400 - ThreadPoolExecutor-0_2 - botocore.parsers - DEBUG - Response headers: {'Date': 'Tue, 14 Jun 2022 23:51:41 GMT', 'Content-Type': 'application/xml', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'x-amz-meta-cid': 'bafybeieurpeyzighqrvwjqyj3szuvbqvrbijm7cdair5a422ipf2d5qnlq', 'ETag': 'W/"d8cad258a3d9bbe03a26a13a3ec43b21"', 'x-amz-request-id': '144e0415-8162-45cd-b071-e51dada956ae', 'x-amz-id-2': 'ZmlsZWJhc2UtNmQ3ZjQ5OGZmZC14ejk1Mg==', 'Server': 'Filebase'}

How to Re-Pin Existing IPFS CIDs With Filebase

Re-Pinning Existing IPFS CIDs from the Filebase Web Console

1. Start by clicking on the ‘Buckets’ option from the menu to open the Buckets dashboard.
2. Once at the Buckets dashboard, create a new IPFS bucket by clicking the ‘Create Bucket’ option in the top right corner.
3. Enter a bucket name and choose the IPFS network.
Bucket names must be unique across all Filebase users, be between 3 and 63 characters long, and can contain only lowercase characters, numbers, and dashes.
4. Then select your new IPFS Bucket.
5. After clicking on the bucket name, select 'Upload' from the top right corner, then select 'CID'.
6. Then enter your IPFS CID and a custom human-readable name to associate with your CID.
7. Select 'Search and Pin' to pin your CID to IPFS through Filebase.
Note: The IPFS network is large and it may take some time for Filebase's IPFS nodes to locate and fetch the CID.

Re-Pinning Existing IPFS CIDs with Filebase Using the IPFS Desktop GUI or IPFS Web UI

  1. 1.
    Start by downloading the IPFS Desktop GUI client, or navigating to the IPFS Web UI.
  2. 2.
    From the left side-bar menu, select 'Settings'.
3. Select 'Add Service' under 'Pinning Services'.
4. Select 'Add a custom one' when prompted to select a pinning service provider.
5. Enter the following configuration information to add Filebase as your pinning service provider:
  • Nickname: Filebase
    • If you intend to use more than one bucket, you will need to repeat this process for each bucket. In this workflow, the nickname should be Filebase(Bucket-Name).
  • API Endpoint: https://api.filebase.io/v1/ipfs
  • Secret Access Token: ACCESS-KEY:SECRET-KEY:BUCKET-NAME encoded in Base64
6. Select 'Save'. Your Filebase pinning service configuration will now be listed under 'Pinning Services'.
7. Next, select 'Files' from the left side-bar menu, then select 'Import'.
8. Select 'From IPFS'.
9. Input your IPFS CID, appended with /ipfs/ and provide a name to associate with your CID, then select 'Import'. This CID can be for an individual file or a folder.
10. Once imported, your IPFS asset will be listed. Select the 3 dots from the right side menu to bring up options to interact with your IPFS asset.
11. Select 'Set pinning'.
12. Select the check box next to 'Filebase', then select 'Apply'.
13. The 'Pin Status' for this IPFS asset will now show an icon with a cloud and a thumbtack, indicating it has been pinned to the configured pinning service.
14. Navigate to the Filebase web console, then select the bucket you used to generate your Secret Access Token earlier, and you will see your pinned IPFS asset, which will show the status 'Pinning', meaning it is in the process of being pinned to IPFS through Filebase. Once finished, this will read 'Pinned'.

Re-Pining Existing IPFS CIDs with Filebase Using the IPFS CLI

  1. 1.
    Start by downloading and installing the Go-IPFS CLI tool.
  2. 2.
    Next, add Filebase as a pinning service with the following command:
ipfs pin remote service add Filebase https://api.filebase.io/v1/ipfs SECRET-ACCESS-TOKEN
If you intend to use more than one bucket, you will need to repeat this command with the secret access token for each bucket. In this workflow, the nickname should be Filebase(Bucket-Name) in order to identify different buckets.
Replace the following value to match your configuration:
3. Use the following command to pin an existing IPFS CID to Filebase:
ipfs pin remote add --service=Filebase --name=ASSET-NAME IPFS-CID
Replace ASSET-NAME with your desired human-readable value to be associated with your pinned CID, and replace IPFS-CID with the CID of your IPFS asset. This can be either a file or a folder.
ipfs pin remote add --service=Filebase --name=my-nft-collection bafybeif5x2gihgepga2vtjlx3lfdwgxquo2sbv4a77rsedokf6poqrrcse
4. Navigate to the Filebase web console, then select the bucket you used to generate your Secret Access Token earlier, and you will see your pinned IPFS asset, which will show the status 'Pinning', meaning it is in the process of being pinned to IPFS through Filebase. Once finished, this will read 'Pinned'.
Your terminal will also return the following output:
CID: bafybeif5x2gihgepga2vtjlx3lfdwgxquo2sbv4a77rsedokf6poqrrcse
Name: my-nft-collection
Status: pinned

How to Retrieve Pinned CIDs Using The AWS S3 SDK for JavaScript

You can also retrieve the IPFS CID using different AWS S3 SDKs. The example below uses The JavaScript SDK:
const AWS = require('aws-sdk');
const fs = require('fs');
const s3 = new AWS.S3({
endpoint: 'https://s3.filebase.com',
region: 'us-east-1',
signatureVersion: 'v4',
fs.readFile('image.png', (err, data) => {
if (err) {
const params = {
Bucket: 'my-ipfs-bucket',
Key: 'test/image.png',
ContentType: 'image/png',
Body: data,
const request = s3.putObject(params);
request.on('httpHeaders', (statusCode, headers) => {
console.log(`CID: ${headers['x-amz-meta-cid']}`);

Further Reading

If you have any questions, please join our Discord server, or send us an email at [email protected]