IPFS Gateways

Learn about the Filebase's IPFS gateway offerings.

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.

Simply put, a gateway is an IPFS peer that accepts HTTP requests for IPFS CIDs.

The IPFS HTTP gateway format follows the structure:

IPFS Public Gateways

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.

The Filebase public IPFS gateway is:

https://ipfs.filebase.io/ipfs/<CID>

The Filebase Public IPFS Gateway has an effective rate limit of 200 RPM (requests per minute).

The Filebase Public IPFS Gateway only serves content stored on Filebase.

Gateways can 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:

https://ipfs.filebase.io/ipfs/QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane

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:

https://ipfs.filebase.io/ipfs/QmYRpH3myNKG2XeaBmdidec3R5HcF9PYBHUVHfks5ysTpq/

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:

https://ipfs.filebase.io/ipfs/<CID>/

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 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:

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.
If the CID hasn’t been cached, the CID will need to be retrieved from the IPFS network.
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.
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 Dedicated Gateways

IPFS Dedicated Gateways at Filebase are unique compared to other IPFS Dedicated Gateway solutions. With Filebase, you are able to create public, private, and scoped gateways.

Public: The gateway can serve any public CID, even ones not pinned by Filebase.
Private: The gateway can only serve CID's that are pinned by Filebase.
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.

Filebase IPFS Dedicated Gateways of any type do not have any request limits.

Filebase IPFS Dedicated Gateways are a feature only available to paid users. They are not available for users on the free tier.

Creating a Dedicated Gateway

Navigate to the Gateways page on the Filebase web console.

Select the ‘Create Gateway’ button in the upper right corner.

A new window will open prompting you to provide a gateway name and select the gateway’s access level.

Gateway names are subject to the same naming restrictions as bucket names. All gateway names must be lowercase, between 3-63 characters, and must be unique.

Gateways can be public, private, or scoped.

Public Gateways

To create a public gateway, select ‘Public’. This can be changed after the gateway has been created.

Private Gateways

To create a private gateway, select ‘Private’. This can be changed after the gateway has been created.

Scoped Gateways

To create a scoped gateway, select ‘Private’, then select a bucket name from the drop-down menu for the scoped gateway to serve. Scoped gateways only serve content located in the bucket that they are restricted to.

Note: If a gateway is configured to serve a root CID, it cannot also be configured to be restricted to a bucket. The root CID configuration must be cleared to configure a bucket restriction.

Alternatively, if you want to set a bucket restriction for a gateway that was previously created, you can set the restriction by navigating to the Buckets menu and selecting the three menu dots for the bucket you’d like to restrict your gateway to. Then select ‘Set Restriction’.

When prompted, select the gateway you want configured to use the selected bucket.

Removing a Bucket Restriction

To remove the bucket restriction on a gateway, navigate to the Gateways page, select the three menu dots on the right-hand side, then select ‘Clear Bucket Restrictions'

You will be prompted to confirm the removal.

Interacting With Gateways

Once a gateway has been created, a subdomain record is created that points to your dedicated gateway. For example, the dedicated gateway called 'documentation' will use the gateway URL:

https://documentation.myfilebase.com/

Toggling Private/Public Access

To toggle between public and private access for a dedicated gateway, use the toggle switch that functions identically to the public and private access toggle switch for buckets.

To interact with the gateway, you can select the three menu dots to open a list of options.

To open the gateway URL, select ‘Open’.

By default, the URL will return the following webpage:

This webpage is returned since there is no CID included in the URL. However, gateways can be configured to serve a CID or file as its root. This means instead of this default webpage, you can configure a different default static webpage or another file to be viewed by default rather than this error message.

This is most commonly used to serve static websites from a domain. Using this feature, http://documentation.myfilebase.com/ would return the file you selected, without having to enter a CID or path in the URL.

Setting a CID as the Root of the Dedicated Gateway

Note: If a gateway is configured to be restricted to a bucket, it cannot be configured to have a root CID. The bucket restriction configuration will need to be cleared before a root CID can be configured for the gateway.

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.

Removing a Root CID From a Gateway

To remove a CID set as the root CID for a dedicated gateway, navigate to the Gateways page, then select the three menu dots and select ‘Clear Root CID’.

You will be prompted to confirm the removal.

Deleting a Gateway

To delete a dedicated gateway, navigate to the Gateways page in the Filebase web console dashboard.

Select the options menu by clicking the three dots on the right-hand side corresponding with the gateway you want to remove. Then select ‘Delete’.

You will be prompted to confirm the removal.

Filebase IPFS Image Optimization

Filebase provides an image optimization functionality directly through the Filebase IPFS dedicated gateway feature.

Through this feature, image load time and the overall image experience can be improved.

Any image file that is uploaded to Filebase can be manipulated through query string parameters. ‌The query string options are defined as follows.

Image Optimization Options ‌

To utilize image optimization, at least one option must be specified.

These parameters can be added to the URL of the image, file. For example:

If the default image URL is:

https://documentation.myfilebase.com/ipfs/QmVnf5PnSUvjrPkc9tDgpwqcreKWh7xVyXDwDmS6xwchWp

The image can be made smaller by adding a parameter to the end of the URL, such as:

https://documentation.myfilebase.com/ipfs/QmVnf5PnSUvjrPkc9tDgpwqcreKWh7xVyXDwDmS6xwchWp?img-width=300

To utilize multiple different image optimizations, multiple options can be specified using comma-separated values. Spaces are not supported.

img-width=x
- Specifies the maximum width of the image in pixels.
img-height=x
- Specifies the maximum height of the image in pixels.
img-dpr=x
- Refers to the device pixel ratio. The default value is 1.
img-fit
- Refers to the image’s width and height. Any resizing modes will retain the image’s aspect ratio. Additional modifiers include:
  - img-fit=scale-down: The image will be decreased in size that matches the provided width or height.
  - img-fit=contain: The image will be resized to be as large as possible within the provided parameters.
  - img-fit=cover: The image will be resized to match the amount specified through the width and height parameters.
  - img-fit=crop: The image will be downsized and cropped to fit within the size specified by the width and height parameters.
  - img-fit=pad: The image will be resized to be as large as possible within the given width or height parameters.
img-gravity
- img-gravity=auto
- img-gravity=side and img-gravity=XxY
img-quality=x
- This parameter specifies the quality of images in the JPEG and WebP formats.
img-format=auto
- This parameter refers to the standard image format JPEG/PNG, which will be used if this option is not specified.
img-anim=false
- This parameter reduces frames for animated images such as GIFs.
img-sharpen=x
- This parameter specifies the strength of the sharpening filter. The value is a floating-point number between 0, which refers to no sharpening, and 10, which refers to maximum sharpening. For most images, 1 is the recommended value.
img-onerror=redirect
img-metadata
- Controls if the metadata should be preserved for the specified image.
  - img-metadata=keep
  - img-metadata=copyright