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?

The InterPlanetary File System, or IPFS, is a decentralized peer-to-peer protocol that enables nodes to store and transfer files between one another.

IPFS isn’t inherently a network itself, like other decentralized storage networks such as Sia. IPFS is a communication protocol that outlines the workflow and components that facilitate the IPFS network to exist. Software such as the IPFS Desktop client or IPFS CLI daemon provides IPFS nodes the ability to interact with other nodes running the same software, in return creating a network of peers that are storing and sharing files between themselves.

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.

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.

Pin Your First File To IPFS

Start by signing up for a Filebase account, then logging into the Filebase dashboard.

Click on the ‘Buckets’ option from the menu to open the Buckets dashboard.

Select your IPFS Bucket. Need to make an IPFS bucket? Check out how to here.After clicking on the bucket name, select 'Upload' in the top right corner. You will have three options:

File: File is for uploading an individual file to IPFS. This can be an image, video, audio, text, or any other file type.
Folder: Folder is for uploading a folder containing multiple files, such as an NFT collection, or the files for a static website.
CID: CID stands for content identifier, and is for re-pinning an existing IPFS CID that you may have from another pinning provider or a local IPFS node.

To upload a single file, choose 'File', then when prompted select the file you want to upload to IPFS.

Once uploaded, confirm that that status reads 'pinned'. You will then be able to view and copy the IPFS CID from the 'CID' category, as seen below.

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'

}

Using the IPFS CLI

Start by downloading and installing the Go-IPFS CLI tool.
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:

SECRET-ACCESS-TOKEN: Navigate to the Filebase Access Keys page, then view the IPFS PInning Service API Endpoint. Click the drop down menu for 'Choose Bucket to Generate Token', then choose the IPFS Filebase Bucket you want to use.
Then copy the generated Secret Access Token:

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

Filebase IPFS Pinning Service API

The IPFS Pinning Service API is a standardized API for re-pinning existing IPFS CIDs. It is often referred to as "remote" pinning or the IPFS "PSA". The IPFS PSA is used by both the IPFS CLI and IPFS Desktop application.

The IPFS development team tracks the compliance of each provider that supports the IPFS PSA to validate each implementation. Filebase is fully compliant with the IPFS PSA requirements. The official compliance report can be seen here.

Filebase supports the IPFS Pinning Service API through our IPFS Re-Pinning service. This API can be used to view pinned objects, add a new object to be pinned, or remove a pinned object.

To interact with the Filebase IPFS Pinning Service API, use the following information below.

API Endpoint

https://api.filebase.io/v1/ipfs

Authentication

To authenticate with the IPFS Pinning Service API, a token is required to be sent with each request in the HTTP headers, using the following format:

Authorization: Bearer <access-token>

The access-token can be generated by navigating to the Filebase Access Keys page, then viewing the IPFS Pinning Service API Endpoint. Click the drop down menu for 'Choose Bucket to Generate Token', then choose the IPFS Filebase Bucket you want to use.

Then copy the generated Secret Access Token:

Payload

Request Body Schema: application/json

To interact with the IPFS Pinning Service API, you need to send a payload in the form of JSON to the API URL. The following is an example of a POST payload:

{
  "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy",
  "name": "image3",
  "meta": {
    "key_name": "value_name"
  }
}

For a full list of the API methods, please see the IPFS Pinning Service documentation page:

Using The AWS S3 SDK for JavaScript with IPFS

You can also retrieve the IPFS CID using different AWS S3 SDKs. The example below uses the JavaScript SDK:

AWS SDK v2:

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) {
        console.error(err);
        return;
    }
    
    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']}`);
    });
    request.send();
});

AWS SDK v3:

const command = new PutObjectCommand({...});

command.middlewareStack.add(
  (next) => async (args) => {
    // Check if request is incoming as middleware works both ways
    const response = await next(args);
    if (!response.response.statusCode) return response;

    // Get cid from headers
    const cid = response.response.headers["x-amz-meta-cid"];
    console.log(cid);
    return response;
  },
  {
    step: "build",
    name: "addCidToOutput",
  },
);

const res = await client.send(command);

With IPFS, file sharing is made extremely easy, since all files uploaded to IPFS are publicly accessible through their CID value. As long as the file is pinned through an IPFS pinning service like Filebase, it’ll be accessible for long-term file sharing.

Start by signing up for a Filebase account, then logging into the Filebase dashboard.

Click on the ‘Buckets’ option from the menu to open the Buckets dashboard.

Select your IPFS Bucket. Need to make an IPFS bucket? Check out how to here.

After clicking on the bucket name, select 'Upload' in the top right corner. You will have three options:

File: File is for uploading an individual file to IPFS. This can be an image, video, audio, text, or any other file type.
Folder: Folder is for uploading a folder containing multiple files, such as an NFT collection, or the files for a static website.
CID: CID stands for content identifier, and is for re-pinning an existing IPFS CID that you may have from another pinning provider or a local IPFS node.

To upload a single file, choose 'File', then when prompted select the file you want to upload to IPFS.

Once uploaded, confirm that that status reads 'pinned'.

Click on the file name to view the file’s details.

From this screen, you’ll see two different URLs listed for your file: its Filebase Object URL and its IPFS Gateway URL.

The Object URL can only be used to share the file if the file is within a public bucket. Otherwise, this URL will return an ‘Access Denied’ error message.

The IPFS Gateway URL can be used to share the file using its IPFS CID and the Filebase Public IPFS Gateway. This URL can be accessed by anyone in the world, regardless if the bucket is public or private.

IPFS Dedicated Gateways

An IPFS gateway is an IPFS peer that accepts HTTP requests for IPFS CIDs. A dedicated gateway provides users with a convenient way to access IPFS content without needing to run an IPFS node themselves. The gateway acts as an intermediary between the user's web browser or application and the IPFS network, retrieving and serving content on behalf of the user.

For a deep dive on IPFS gateways and how they work, plus a full walkthrough of using IPFS gateways on Filebase, see our documentation here:

Filebase users that are on a paid IPFS subscription plan have access to Filebase IPFS Dedicated Gateways. Dedicated Gateways come with several benefits, such as:

Increased performance and retrieval times.
No rate limits when accessing content through the dedicated gateway.
Limiting content (whitelisting) that the gateway can serve through the Scope feature of a dedicated gateway.
Setting a Root CID of the gateway that can be used for website or app hosting.

Creating a Gateway

Navigate to the Gateways page on the Filebase web console. Select the ‘Create Gateway’ button in the upper right corner.

What’s the difference between Public, Private, and Scoped?

Public: The gateway can serve any public CID, even ones not pinned by Filebase. Public gateways are great for widespread data accessibility but can incur higher bandwidth usage charges.

Private: The gateway can only serve CID's that are pinned by Filebase. Private gateways are not limited to CIDs that a user has uploaded to their Filebase account - anything pinned by Filebase can be served via a private gateway.

Scoped: The gateway is tied to a bucket and can only serve content from that specific bucket. Any CIDs for content not stored in the specified bucket will return a 404 Not Found message. Scoped gateways are great for whitelisting content and controlling gateway usage.

What Does ‘Bandwidth’ Mean?

Bandwidth refers to the amount of data required to display or download the content that you or your users access through the dedicated gateway. Whether it's an image, video, audio, or any other type of file, the data that makes up the content is transmitted from an IPFS node to your device, and the quantity of this data is what determines the bandwidth.

Filebase only charges for Bandwidth for outgoing data transfer (egress). Upload bandwidth (ingress) is always free.

How To Use a Gateway

IPFS Dedicated Gateways can be used for retrieving and accessing IPFS content in the same way a public gateway is, such as using the format:

https://my-gateway.myfilebase.com/ipfs/IPFS_CID

Filebase IPFS dedicated gateways can also be used to serve a specific CID through setting a Root CID that will be served by the gateway without specifying the CID in the URL.

To configure this, navigate to the Buckets menu, and select an IPFS bucket. Once inside the bucket, select the file you’d like to set as the root file by selecting the three menu dots on the right-hand side.

Select ‘Set as Root’.

Then choose the dedicated gateway you’d like to use.

Now, when you open the gateway, you’ll see the file you set as the root file displayed rather than the default error message.

Where Can I Use an IPFS Dedicated Gateway URL?

IPFS Dedicated Gateway URLs can be used in place of any IPFS native URL (ipfs://) or any IPFS Public Gateway URL (such as https://ipfs.io/ipfs). This means dedicated gateways can be used for in workflows such as:

Hosting digital assets such as photos, videos, documents, certificates, or other digital files.
Referring to NFT assets in Metadata files or Smart Contracts.
Sharing files and folders.
Hosting decentralized applications.
Hosting static websites.
Sharing code repositories or software packages.
Sharing public resources like eBooks, PDFs, or videos.