-
Notifications
You must be signed in to change notification settings - Fork 428
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: remote pinning services (#369)
Basic docs related to pin remote commands: https://github.com/ipfs/go-ipfs/releases/v0.8.0 Co-authored-by: Johnny <[email protected]> Co-authored-by: Marcin Rataj <[email protected]>
- Loading branch information
3 people
authored
Feb 19, 2021
1 parent
1d12646
commit b18f003
Showing
3 changed files
with
152 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| --- | ||
| title: Work with pinning services | ||
| description: Learn how to use or create remote pinning services with IPFS, the InterPlanetary File System. | ||
| --- | ||
|
|
||
| # Work with remote pinning services | ||
|
|
||
| Depending on how you use IPFS, you might find it helpful to use a **remote pinning service** instead of, or in addition to, pinning files on your local IPFS node. Whether it happens remotely or locally, **pinning** an item in IPFS identifies it as something you always wish to keep available, exempting it from the routine _garbage collection_ that IPFS does on infrequently-used items in order to efficiently manage storage space. [Learn more about local pinning →](/how-to/pin-files) | ||
|
|
||
| If you've got just one local IPFS node that's always running, local pinning may be all you need to ensure your important items are persisted and never garbage-collected. However, using a remote pinning service — or creating your own — might be useful to you if: | ||
|
|
||
| - Your local node isn't always online, but you need items to be consistently available. | ||
| - You'd like to keep a persistent backup of your local node's files somewhere else. | ||
| - You don't have all the disk space you need on your local node. | ||
| - You run more than one IPFS node, and would like to use one of them as a "personal pinning service" as your preferred location for permanent storage. | ||
|
|
||
| There are a number of commercial pinning services that make it easy for you to purchase pinning capacity for your important files, some of which include Pinata, Temporal, Infura, and others. Each of these third-party services has its own unique interface for pinning files and managing those pins; this could include a GUI, an API, CLI commands, or other tooling. | ||
|
|
||
| However, you don't need to learn new commands or tools if your pinning service of choice supports the vendor-agnostic [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) specification. Those services are supported within IPFS itself through the command line: `ipfs pin remote --help`. | ||
|
|
||
| As of January 2021, [Pinata](https://pinata.cloud/) supports the [IPFS Pinning Service API endpoint](https://pinata.cloud/documentation#PinningServicesAPI), with more pinning services on the way! [Learn how to create your own →](#create-your-own-pinning-service) | ||
|
|
||
| ## Use an existing pinning service | ||
|
|
||
| To add and use a remote pinning service directly in IPFS, you'll first need to have an account with that service. Once you've got an account, follow these steps to add and use it: | ||
|
|
||
| <!-- TODO: GUI section can be uncommented after https://github.com/ipfs/ipfs-gui/issues/91 is closed | ||
| ### IPFS Desktop or IPFS Web UI | ||
| You can add your favorite pinning service(s) to IPFS Desktop/Web UI directly, enabling you to pin and unpin items from the Files screen in the same way as as you do local pins. | ||
| #### Adding a new pinning service | ||
| To add a new pinning service, open up IPFS Desktop or Web UI, navigate to the **Pinning Services** section of the **Settings** screen, and click the **Add Service** button: | ||
|  | ||
| Then, select your chosen pinning service from the modal that pops up. If the pinning service you'd like to add isn't listed in that modal, don't worry — you can add any remote pinning service that supports the IPFS Pinning Service API by clicking the **Add a custom one** link. | ||
|  | ||
| In the next screen, you’ll be asked for a few other details: | ||
| - A nickname for this service. This can be helpful if, for example, you want to add two accounts from the same service. | ||
| - The URL for your service's API endpoint. _Note: This field only appears if you've selected a custom pinning service!_ | ||
| - Your secret API key. This is the unique token provided to you by the pinning service — check its documentation for more info. | ||
| - Whether you want to automatically add all files in your local node’s Files directory to the pinning service, or choose which ones you upload. | ||
|  | ||
| After you hit **Save**, you’ll see your new pinning service added to the **Pinning Services** section of your **Settings** screen. | ||
|  | ||
| #### Using a pinning service | ||
| Now that you’re set up, you can pin or unpin files to your new pinning service directly from the Files screen. Just right-click any file or click the **three dots** action icon in the files list, and select **Set pinning**: | ||
|  | ||
| --> | ||
|
|
||
| ### IPFS CLI | ||
|
|
||
| Command-line users benefit from `ipfs pin remote` commands, which simplify remote pinning operations. The built-in pinning service API client executes all the necessary remote calls under the hood. | ||
|
|
||
| #### Adding a new pinning service | ||
|
|
||
| To add a new pinning service, use the following command: | ||
|
|
||
| ```console | ||
| $ ipfs pin remote service add nickname https://my-pin-service.example.com/api-endpoint myAccessToken | ||
| ``` | ||
|
|
||
| - `nickname` is a unique name for this particular instantiation of a pinning service. This can be helpful if, for example, you want to add two accounts from the same service. | ||
| - `https://my-pin-service.example.com/api-endpoint` is the endpoint supplied to you by the pinning service. Check the service's documentation for more info. | ||
| - `myAccessToken` is the unique secret token provided to you by the pinning service. Check the service's documentation for more info. | ||
|
|
||
| #### Using a pinning service | ||
|
|
||
| Here are a few CLI commands to get you started. In all examples, replace `nickname` with the unique name you gave the pinning service when you added it. | ||
|
|
||
| To pin a CID under under a human-readable name: | ||
|
|
||
| ```console | ||
| $ ipfs pin remote add --service=nickname --name=war-and-peace.txt bafybeib32tuqzs2wrc52rdt56cz73sqe3qu2deqdudssspnu4gbezmhig4 | ||
| ``` | ||
|
|
||
| To list successful pins: | ||
|
|
||
| ```console | ||
| $ ipfs pin remote ls --service=nickname | ||
| ``` | ||
|
|
||
| To list all "pending" pins: | ||
|
|
||
| ```console | ||
| $ ipfs pin remote ls --service=nickname --status=queued,pinning,failed | ||
| ``` | ||
|
|
||
| For more commands and general help: | ||
|
|
||
| ```console | ||
| $ ipfs pin remote --help | ||
| ``` | ||
|
|
||
| ## Create your own pinning service | ||
|
|
||
| Obviously you aren't limited to a static list of pre-approved services. Any remote pinning service compatible with the [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec) can be added as a custom pinning service — which also means that you can create your own! This might be useful in circumstances like: | ||
|
|
||
| - Designating one of your own IPFS nodes to be a _personal pinning service_ as a preferred location for permanent storage. | ||
| - Running a private pinning service for your friends or company. | ||
| - Starting your own commercial pinning service. | ||
|
|
||
| As noted above, your service must use the [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec) in order to be interoperable with client behind `ipfs pin remote` commands. | ||
|
|
||
|
|
||
| ::: tip | ||
| If you're interested in creating your own pinning service for your own personal or shared use, you can [generate client and server from the OpenAPI spec](https://github.com/ipfs/pinning-services-api-spec#code-generation), reducing the development time. | ||
|
|
||
| You may also wish to read continuing details on how the API is evolving in the [Pinning Service API Spec GitHub repo](https://github.com/ipfs/pinning-services-api-spec), and be part of the discussion on its further development! | ||
| ::: | ||
|
|
||
|
|
||
| <!-- TODO this call to action can be uncommented when https://github.com/ipfs/ipfs-gui/issues/91 is closed | ||
| If you'd like to make your custom pinning service available to every IPFS user, we welcome your submissions. Once you're ready to open the doors to the public, make a PR against the [IPFS Web UI GitHub repo](https://github.com/ipfs-shipyard/ipfs-webui) in order to add it to the default list of pinning services that are displayed in the Desktop/Web UI Settings screen, and one of the core maintainers will be in touch. | ||
| --> |