Storj IPFS Pinning Service (Beta)
Prerequisites
You should have received an email that you have been invited to the beta which will include credentials to access the service. If you have not signed up yet, you can Join the beta.
The Storj IPFS Pinning service consists of an HTTP endpoint for uploading and pinning content, and an IPFS Gateway that serves the pinned content over IPFS and HTTP. Details on smart contract pinning will be made available in the future.
How to pin with Storj IPFS
All content uploaded to the Storj IPFS service via the HTTP endpoint below is pinned. Examples are given in cURL and JavaScript, but could be done from any programming language or with existing IPFS client bindings for a given programming language, such as the IPFS HTTP Client library for npm.
HTTP Upload endpoint
Uploading content follows the IPFS HTTP RPC for /api/v0/add with two minor differences:
- The only optional arguments supported are wrap-with-directory and cid-version.
- You must specify the credentials given when invited to participate in the beta as HTTP basic authentication.
This is not the same as your Storj DCS username and password. Do not use your Storj DCS username and password to try and use the IPFS Pinning Service.
Example for pinning a single file using cURL
For example, this is how it would work with cURL and a file you wanted to pin called /path/file.extension. Please replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
The '@' before the file path is required for the upload to work properly. For example, if the file you wanted to upload was /home/hello/hi.jpg, the curl argument would be file=@/home/hello/hi.jpg.
Example for pinning a single file using cURL and optional arguments
Another example is to pin the same file /path/file.extension, but wrap it in a directory and use CIDv1 instead of the default CIDv0 for the content identifier. Again, replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
The '@' before the file path is required for the upload to work properly. For example, if the file you wanted to upload was /home/hello/hi.jpg, the curl argument would be file=@/home/hello/hi.jpg.
Example for pinning a single file using JavaScript
You'll need Node.js installed on your local system for this example.
1. Make a new JavaScript project.
Create a new directory and use npm to create a new project:
NPM will ask a few questions about your project and create a package.json file.
2. Add the got HTTP client and the form-data library to your project dependencies.
Install the latest versions of the got and form-data packages:
3. Create a file called upload-file.mjs and open it with your code editor.
A .mjs extension indicates an ES6 module file. For more details see here.
Below is the code we need to upload a file and pin it on the Storj IPFS pinning service.
Paste in the code below and read through it. Feel free to remove the comments - they're just there to highlight what's happening.
4. Run your script with node.
You should now be able to run the script and give it the path to a file. You'll also need to supply your username and password for the Storj IPFS pinning service.
Please replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
Example for pinning a folder using JavaScript
This example builds on top of the example for pinning a single file.
1. Add the recursive-js and base-path-converter libraries to your project dependencies.
Install the latest versions of the recursive-js and base-path-converter packages:
2. Create a file called upload-folder.mjs and open it with your code editor.
A .mjs extension indicates an ES6 module file. For more details see here.
Below is the code we need to upload a folder and pin it on the Storj IPFS pinning service.
Paste in the code below and read through it. Feel free to remove the comments - they're just there to highlight what's happening.
3. Run your script with node.
You should now be able to run the script and give it the path to a folder. You'll also need to supply your username and password for the Storj IPFS pinning service.
Please replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
How to retrieve pinned objects
Any content uploaded is automatically pinned and retrievable through any software that supports IPFS natively via its CID like IPFS Desktop or IPFS CLI. Some browsers like Brave include support, as well as some IPFS programs.
For those applications that do not support IPFS natively, you can use any public IPFS gateway, or the Storj IPFS Gateway as described below.
HTTP via Storj IPFS Gateway
For best performance, we have provided a Storj IPFS Gateway. This gateway will only host content pinned to Storj DCS, so it is not like other public IPFS gateways.
You can construct a link like this:
In cases where the gateway is unable to retrieve a given CID (e.g., returns a 404 not found error), please double check that you are using the correct CID and that it was uploaded to the Storj IPFS service.
Peering your IPFS node with Storj pinning nodes
If you run your own IPFS node that retrieves a lot of data pinned on the Storj IPFS Pinning Service, you may want to prioritize the connections to the Storj IPFS nodes. This will improve the download performance by bypassing the DHT lookup for the data.
Prioritizing connections to certain peers is called Peering, and you can tell IPFS which peers to prioritize by editing the Peering configuration in your IPFS config file.
To peer with Storj IPFS nodes, you could update the Peering section of your config to include their ID and addresses:
How to list pinned objects
Listing pinned content follows the IPFS HTTP RPC for /api/v0/pin/ls with two minor differences:
- None of the optional arguments are currently supported.
- You must specify the credentials given when invited to participate in the beta as HTTP basic authentication.
This is not the same as your Storj DCS username and password. Do not use your Storj DCS username and password to try and use the IPFS Pinning Service.
Example for listing pins using cURL
For example, this is how it would work with cURL to list all pins for your user. Please replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
How to unpin objects
Unpinning content follows the IPFS HTTP RPC for /api/v0/pin/rm with two minor differences:
- None of the optional arguments are currently supported.
- You must specify the credentials given when invited to participate in the beta as HTTP basic authentication.
This is not the same as your Storj DCS username and password. Do not use your Storj DCS username and password to try and use the IPFS Pinning Service.
Unpinning the content does not remove it immediately from the IPFS network, and it may still be accessible through the Storj IPFS Gateway for some time.
Example for removing a single pin using cURL
For example, this is how it would work with cURL and a pin with CID QmExample. Please replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
Example for removing multiple pins using cURL
For example, this is how it would work with cURL and three pins with CIDs QmExample1, QmExample2, and QmExample3. Please replace ipfs_beta_user and ipfs_beta_password with the beta credentials you received when accepted into the beta.
