From 63f88a27515078c4144b37c4e328391db2bb1918 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Tue, 14 Jul 2020 12:11:50 -0600 Subject: [PATCH 01/28] Sketch out pinning service page; amend existing pining page --- docs/.vuepress/config.js | 1 + docs/how-to/pin-files.md | 20 +++++++++--- docs/how-to/work-with-pinning-services.md | 40 +++++++++++++++++++++++ 3 files changed, 56 insertions(+), 5 deletions(-) create mode 100644 docs/how-to/work-with-pinning-services.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 22fcd0fe0..82dfe64ab 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -204,6 +204,7 @@ module.exports = { ], '/how-to/work-with-blocks', '/how-to/pin-files', + '/how-to/work-with-pinning-services', [ 'https://github.com/ipfs/go-ipfs/blob/master/docs/file-transfer.md', 'Troubleshoot file transfers' diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index 964e3cda1..ceb45b2af 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -6,7 +6,11 @@ description: Learn how to pin files in IPFS in order to keep your files and othe # Pin files using IPFS -Pinning is a very important concept in IPFS. IPFS semantics try to make it feel like every single object is local — there is no "retrieve this file for me from a remote server", just `ipfs cat` or `ipfs get`, which act the same way no matter where the actual object is located. While this is nice, sometimes you want to be able to control what you keep around. Pinning is the mechanism that allows you to tell IPFS to always keep a given object local. IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any IPFS operation on it, but these objects may get garbage-collected fairly regularly. To prevent that garbage collection, simply pin the hash you care about. Objects added through `ipfs add` are pinned recursively by default. +Pinning is a very important concept in IPFS. IPFS semantics try to make it feel like every single object is local — there is no "retrieve this file for me from a remote server", just `ipfs cat` or `ipfs get`, which act the same way no matter where the actual object is located. + +While this is nice, sometimes you want to be able to control what you keep around. **Pinning** is the mechanism that allows you to tell IPFS to always keep a given object somewhere — the default being your local node, though this can be different if you use a third-party remote pinning service (see below for details). IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any IPFS operation on it, but these objects may get garbage-collected fairly regularly. To prevent that garbage collection, simply pin the hash you care about. Note that objects added through `ipfs add` are pinned recursively by default. + +Let's look at this example to explore pinning to your local IPFS node in a bit more depth: ``` echo "ipfs rocks" > foo @@ -19,11 +23,11 @@ ipfs pin ls --type=all ## Three kinds of pins -As you may have noticed, the first `ipfs pin rm` command didn't work — it should have warned you that the given hash was "pinned recursively". There are three types of pins in the IPFS world: +As you may have noticed in the example above, the first `ipfs pin rm` command didn't work — it should have warned you that the given hash was "pinned recursively". What does this mean? There are three types of pins in the IPFS world: -- Direct pins, which pin just a single block, and no others in relation to it -- Recursive pins, which pin a given block and all of its children -- Indirect pins, which are the result of a given block's parent being pinned recursively +- **Direct pins**, which pin just a single block and no others in relation to it +- **Recursive pins**, which pin a given block and all of its children +- **Indirect pins**, which are the result of a given block's parent being pinned recursively A pinned object cannot be garbage-collected — try this for proof: @@ -40,3 +44,9 @@ ipfs pin rm -r ipfs repo gc ipfs cat ``` + +## Local vs. remote pinning + +All the information above assumes that you're pinning items locally — that is, to your local IPFS node. That's the default behavior for IPFS, but it's also possible to pin your files to a _remote pinning service_. These third-party services offer the opportunity for you to pin files not to your own local node, but to nodes that they operate, meaning that you don't need to worry about your own node's available disk space or uptime when it comes to availability. + +[IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) and its equivalent in-browser IPFS web interface, the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui), both support integration with remote pinning services so you can pin either remotely or locally straight from the UI. [Learn more here.](/how-to/work-with-pinning-services/) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md new file mode 100644 index 000000000..2b65ce134 --- /dev/null +++ b/docs/how-to/work-with-pinning-services.md @@ -0,0 +1,40 @@ +--- +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 + +Intro: Use a (third-party, remote) pinning service or create your own + +Local vs remote pinning services: when to use which one. +Use local pinning to ensure files on your local node persist and are never garbage-collected. You can also link your accounts with other
pinning services to automatically or selectively persist files with those providers, enabling you to keep backup copies of your files and/or make them available to others when your local node is offline. Check the documentation for further information. + +Why would using a remote pinning service be useful? + +- reason +- reason +- reason + +## Use an existing pinning service + +To add and use a third-party (remote) pinning service ... + +You do this in Desktop/Web UI. + +First you'll need to subscribe to one or more pinning services. You might need to pay for them. Then, you'll need to know ... secret key? + +TODO: Add screenshots + +## Create your own pinning service + +Create your own custom pinning service for fun and/or profit. + +Why is this useful? + +- multiple of your own nodes +- other reasons + +You'll need to use the API. Text here. + +If you'd like to make your custom service globally available, make a PR against Web UI. From c160ecfc8b69850281e13e005655336762a51af9 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Tue, 14 Jul 2020 13:47:27 -0600 Subject: [PATCH 02/28] First draft of pinning services page --- docs/how-to/work-with-pinning-services.md | 39 ++++++++++++----------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 2b65ce134..c9603f0bc 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -5,36 +5,39 @@ description: Learn how to use or create remote pinning services with IPFS, the I # Work with remote pinning services -Intro: Use a (third-party, remote) pinning service or create your own +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** something 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 objects in order to efficiently manage storage space. (For more details on pinning as a concept, [see this guide](/how-to/pin-files).) -Local vs remote pinning services: when to use which one. -Use local pinning to ensure files on your local node persist and are never garbage-collected. You can also link your accounts with other
pinning services to automatically or selectively persist files with those providers, enabling you to keep backup copies of your files and/or make them available to others when your local node is offline. Check the documentation for further information. +If you've got a single, always-on local IPFS node, local pinning may be all you need to insure your important items are persisted and never garbage-collected. However, using a remote pinning service might be useful to you if: -Why would using a remote pinning service be useful? +- 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 designate one as your preferred location for permanent storage -- reason -- reason -- reason +Many remote pinning services operate as commercial endeavors (examples of these include Pinata, Temporal, Infura, and others), enabling you to purchase pinning capacity and offering an interface for the pinning action itself. However, if you don't want to bother with using more than one interface, integrating remote pinning services with IPFS can be simple. [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) and its equivalent in-browser IPFS web interface, the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui), both support integration with remote pinning services so you can pin either remotely or locally straight from the UI. ## Use an existing pinning service -To add and use a third-party (remote) pinning service ... +To add and use a remote pinning service in IPFS Desktop or Web UI, you'll first need to have an account with that service (you can do this by signing up directly with the service itself). Once you're got an account, follow these steps to add it to Desktop or Web UI: -You do this in Desktop/Web UI. +_Instructions and screenshots to come when workflow finalized_ -First you'll need to subscribe to one or more pinning services. You might need to pay for them. Then, you'll need to know ... secret key? +If your remote pinning service isn't listed here, don't worry — you can add any remote pinning service you'd like by specifying the following information: -TODO: Add screenshots +_Details to come when custom add workflow finalized_ -## Create your own pinning service +Then, to pin a file: + +_Details to come when workflow finalized, particularly manual/automatic rules_ -Create your own custom pinning service for fun and/or profit. +## Create your own pinning service -Why is this useful? +As noted above, you aren't limited to adding the remote pinning services listed in the Settings screen. Any remote pinning service that uses 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: -- multiple of your own nodes -- other reasons +- Designating one of your own IPFS nodes as a preferred location for permanent storage +- Running a private pinning service for your friends or company +- Starting your own commercial remote pinning service -You'll need to use the API. Text here. +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 IPFS Desktop and Web UI. 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! -If you'd like to make your custom service globally available, make a PR against Web UI. +If you'd like to make your custom remote pinning service available to every IPFS user, you can 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. From 9d2a2686cbef8e0e455966fc7c637b1da7d080b9 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 23 Jul 2020 13:51:35 -0600 Subject: [PATCH 03/28] Update docs/how-to/pin-files.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/pin-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index ceb45b2af..045812bdc 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -45,7 +45,7 @@ ipfs repo gc ipfs cat ``` -## Local vs. remote pinning +## Local versus remote pinning All the information above assumes that you're pinning items locally — that is, to your local IPFS node. That's the default behavior for IPFS, but it's also possible to pin your files to a _remote pinning service_. These third-party services offer the opportunity for you to pin files not to your own local node, but to nodes that they operate, meaning that you don't need to worry about your own node's available disk space or uptime when it comes to availability. From a7310446bfb46e8a79e63cbbbe7e47a7a6a9b7e7 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Thu, 17 Dec 2020 17:19:07 -0700 Subject: [PATCH 04/28] Update copy, placeholder screenshots --- docs/how-to/pin-files.md | 6 +- docs/how-to/work-with-pinning-services.md | 101 ++++++++++++++++++---- 2 files changed, 91 insertions(+), 16 deletions(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index 045812bdc..b917a068d 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -49,4 +49,8 @@ ipfs cat All the information above assumes that you're pinning items locally — that is, to your local IPFS node. That's the default behavior for IPFS, but it's also possible to pin your files to a _remote pinning service_. These third-party services offer the opportunity for you to pin files not to your own local node, but to nodes that they operate, meaning that you don't need to worry about your own node's available disk space or uptime when it comes to availability. -[IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) and its equivalent in-browser IPFS web interface, the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui), both support integration with remote pinning services so you can pin either remotely or locally straight from the UI. [Learn more here.](/how-to/work-with-pinning-services/) +While you can use a remote pinning service's own GUI, CLI, or other dev tools to manage IPFS files pinned to their service, you can also work directly with pinning services in IPFS itself — meaning that you don't need to learn a pinning service's unique API or other tooling. + +- The [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) offers a specification that enables developers to integrate any pinning service that supports the spec, using simple, standardized schemas and fields. +- If you use go-ipfs from the command line, you can add your favorite pinning service(s), pin CIDs under human-readable names, get pin statuses, and more straight from the CLI. [Learn how →](/how-to/work-with-pinning-services/) +- [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) and its equivalent in-browser IPFS web interface, the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui), both support remote pinning services, so you can pin to your favorite pinning service(s) straight from the UI. [Learn how →](/how-to/work-with-pinning-services/) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index c9603f0bc..4d4a25247 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -5,39 +5,110 @@ description: Learn how to use or create remote pinning services with IPFS, the I # 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** something 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 objects in order to efficiently manage storage space. (For more details on pinning as a concept, [see this guide](/how-to/pin-files).) +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. (For more details on pinning as a concept, [see this guide](/how-to/pin-files).) -If you've got a single, always-on local IPFS node, local pinning may be all you need to insure your important items are persisted and never garbage-collected. However, using a remote pinning service might be useful to you if: +If you've got just one local IPFS node, and it's always running, local pinning may be all you need to insure 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 designate one as your preferred location for permanent storage +- 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 -Many remote pinning services operate as commercial endeavors (examples of these include Pinata, Temporal, Infura, and others), enabling you to purchase pinning capacity and offering an interface for the pinning action itself. However, if you don't want to bother with using more than one interface, integrating remote pinning services with IPFS can be simple. [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) and its equivalent in-browser IPFS web interface, the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui), both support integration with remote pinning services so you can pin either remotely or locally straight from the UI. +There are a number of commercial pinning services that make it easy for you to purchase pinning capacity for your important files (examples of these 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 [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) specification — because those pinning services are supported within IPFS itself via the command line, [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), and the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui). And, if you're interested in creating your own pinning service for your own personal or shared use, you can directly integrate it with IPFS Desktop/Web UI and the IPFS CLI by using the IPFS Pinning Service API. + +As of January 2021, [Pinata](https://pinata.cloud/) supports the IPFS Pinning Service API, with more pinning services on the way! ## Use an existing pinning service -To add and use a remote pinning service in IPFS Desktop or Web UI, you'll first need to have an account with that service (you can do this by signing up directly with the service itself). Once you're got an account, follow these steps to add it to Desktop or Web UI: +To add and use a remote pinning service directly in IPFS, you'll first need to have an account with that service (you can do this by signing up directly with the service itself). Once you're got an account, follow these steps to add and use it: + +### 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: + +![The Desktop/Web UI Settings screen, ready for adding a new pinning service](https://user-images.githubusercontent.com/1507828/102558464-b0c07700-408a-11eb-8ae4-cd30e3ce81fd.png) + +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. + +![Desktop/Web UI modal for selecting a pinning service to add](https://user-images.githubusercontent.com/1507828/102558471-b918b200-408a-11eb-9a28-b06d03f99121.png) + +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 + +![Details modals for adding a new pinning service or a new custom pinning service in Desktop/Web UI](https://user-images.githubusercontent.com/1507828/102558910-ca15f300-408b-11eb-9fe3-742186c077c7.png) + +After you hit “Save”, you’ll see your new pinning service added to the “Pinning Services” section of your Settings screen. + +![Desktop/Web UI Settings screen with a new pinning service added](https://user-images.githubusercontent.com/1507828/102558530-db123480-408a-11eb-9e3b-58bbd59b2880.png) + +#### 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”: + +![Desktop/Web UI Files screen with the action menu open and "Set pinning" visible](https://user-images.githubusercontent.com/1507828/102558546-e6656000-408a-11eb-97b8-5fdb060602d2.png) + +### IPFS CLI + +In addition to integrating your favorite pinning service into IPFS Desktop or Web UI, you can also use it directly from the command line using the `ipfs` command. + +#### Adding a new pinning service + +To add a new pinning service, use the following command: + +```bash +ipfs pin remote service add nickname https://api.mypinningservice.com/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://api.mypinningservice.com/endpoint` is the endpoint supplied to you by the pinning service (check its documentation for more info) +- `myAccessToken` is the unique token provided to you by the pinning service (check its 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: + +```bash +ipfs pin remote add --service=nickname --name=war-and-peace.txt bafybeib32tuqzs2wrc52rdt56cz73sqe3qu2deqdudssspnu4gbezmhig4 +``` + +To list successful pins: -_Instructions and screenshots to come when workflow finalized_ +```bash +ipfs pin remote ls --service=nickname +``` -If your remote pinning service isn't listed here, don't worry — you can add any remote pinning service you'd like by specifying the following information: +To list pending pins: -_Details to come when custom add workflow finalized_ +```bash +ipfs pin remote ls --service=nickname --status=queued,pinning,failed +``` -Then, to pin a file: +For more commands and general help: -_Details to come when workflow finalized, particularly manual/automatic rules_ +```bash +ipfs pin remote --help +``` ## Create your own pinning service -As noted above, you aren't limited to adding the remote pinning services listed in the Settings screen. Any remote pinning service that uses 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: +As noted above, you aren't limited to adding the remote pinning services listed in the Settings screen of Desktop/Web UI. Any remote pinning service that uses 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 as a preferred location for permanent storage +- 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 remote pinning service +- 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 IPFS Desktop and Web UI. 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! +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 IPFS Desktop/Web UI and the IPFS CLI. 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! -If you'd like to make your custom remote pinning service available to every IPFS user, you can 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. +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. From 087c55fa0c02dd596c694de4c1ab78292e51fc45 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:36:06 -0700 Subject: [PATCH 05/28] Update docs/how-to/pin-files.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/pin-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index b917a068d..2dcda86da 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -8,7 +8,7 @@ description: Learn how to pin files in IPFS in order to keep your files and othe Pinning is a very important concept in IPFS. IPFS semantics try to make it feel like every single object is local — there is no "retrieve this file for me from a remote server", just `ipfs cat` or `ipfs get`, which act the same way no matter where the actual object is located. -While this is nice, sometimes you want to be able to control what you keep around. **Pinning** is the mechanism that allows you to tell IPFS to always keep a given object somewhere — the default being your local node, though this can be different if you use a third-party remote pinning service (see below for details). IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any IPFS operation on it, but these objects may get garbage-collected fairly regularly. To prevent that garbage collection, simply pin the hash you care about. Note that objects added through `ipfs add` are pinned recursively by default. +While this is nice, sometimes you want to be able to control what you keep around. **Pinning** is the mechanism that allows you to tell IPFS to always keep a given object somewhere — the default being your local node, though this can be different if you use a [third-party remote pinning service](#using-a-pinning-service). IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any IPFS operation on it, but these objects may get garbage-collected regularly. To prevent that garbage collection, simply pin the hash you care about. Objects added through `ipfs add` are pinned recursively by default. Let's look at this example to explore pinning to your local IPFS node in a bit more depth: From b275852b31365af963382861fccf6e3a7aca6451 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:36:33 -0700 Subject: [PATCH 06/28] Update docs/how-to/pin-files.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/pin-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index 2dcda86da..0f9e7ca73 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -23,7 +23,7 @@ ipfs pin ls --type=all ## Three kinds of pins -As you may have noticed in the example above, the first `ipfs pin rm` command didn't work — it should have warned you that the given hash was "pinned recursively". What does this mean? There are three types of pins in the IPFS world: +As you may have noticed in the example above, the first `ipfs pin rm` command didn't work — it should have warned you that the given hash was _pinned recursively_. What does this mean? There are three types of pins in the IPFS world: - **Direct pins**, which pin just a single block and no others in relation to it - **Recursive pins**, which pin a given block and all of its children From bcd6df17127f71411a4de977cb294b32d357109a Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:36:43 -0700 Subject: [PATCH 07/28] Update docs/how-to/pin-files.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/pin-files.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index 0f9e7ca73..877522994 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -25,9 +25,9 @@ ipfs pin ls --type=all As you may have noticed in the example above, the first `ipfs pin rm` command didn't work — it should have warned you that the given hash was _pinned recursively_. What does this mean? There are three types of pins in the IPFS world: -- **Direct pins**, which pin just a single block and no others in relation to it -- **Recursive pins**, which pin a given block and all of its children -- **Indirect pins**, which are the result of a given block's parent being pinned recursively +- **Direct pins**, which pin just a single block and no others in relation to it. +- **Recursive pins**, which pin a given block and all of its children. +- **Indirect pins**, which are the result of a given block's parent being pinned recursively. A pinned object cannot be garbage-collected — try this for proof: From 5bafed8cfe3a622a17e25e0d9ec15eb1bffd7b98 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:36:59 -0700 Subject: [PATCH 08/28] Update docs/how-to/pin-files.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/pin-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index 877522994..54cc1e24a 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -47,7 +47,7 @@ ipfs cat ## Local versus remote pinning -All the information above assumes that you're pinning items locally — that is, to your local IPFS node. That's the default behavior for IPFS, but it's also possible to pin your files to a _remote pinning service_. These third-party services offer the opportunity for you to pin files not to your own local node, but to nodes that they operate, meaning that you don't need to worry about your own node's available disk space or uptime when it comes to availability. +All the information above assumes that you're pinning items locally — that is, to your local IPFS node. That's the default behavior for IPFS, but it's also possible to pin your files to a _remote pinning service_. These third-party services give you the opportunity to pin files not to your own local node, but to nodes that they operate. You don't need to worry about your own node's available disk space or uptime. While you can use a remote pinning service's own GUI, CLI, or other dev tools to manage IPFS files pinned to their service, you can also work directly with pinning services in IPFS itself — meaning that you don't need to learn a pinning service's unique API or other tooling. From 472315e72c894da7ee30b561557e4044c74e1e83 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:37:20 -0700 Subject: [PATCH 09/28] Update docs/how-to/pin-files.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/pin-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index 54cc1e24a..aa950b817 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -49,7 +49,7 @@ ipfs cat All the information above assumes that you're pinning items locally — that is, to your local IPFS node. That's the default behavior for IPFS, but it's also possible to pin your files to a _remote pinning service_. These third-party services give you the opportunity to pin files not to your own local node, but to nodes that they operate. You don't need to worry about your own node's available disk space or uptime. -While you can use a remote pinning service's own GUI, CLI, or other dev tools to manage IPFS files pinned to their service, you can also work directly with pinning services in IPFS itself — meaning that you don't need to learn a pinning service's unique API or other tooling. +While you can use a remote pinning service's own GUI, CLI, or other dev tools to manage IPFS files pinned to their service, you can also work directly with pinning services using your local IPFS installation — meaning that you don't need to learn a pinning service's unique API or other tooling. - The [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) offers a specification that enables developers to integrate any pinning service that supports the spec, using simple, standardized schemas and fields. - If you use go-ipfs from the command line, you can add your favorite pinning service(s), pin CIDs under human-readable names, get pin statuses, and more straight from the CLI. [Learn how →](/how-to/work-with-pinning-services/) From faf1a21c65e9a3ca3a362ebce1ba692aebcf3574 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:37:43 -0700 Subject: [PATCH 10/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 4d4a25247..69e1e1681 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -5,7 +5,7 @@ description: Learn how to use or create remote pinning services with IPFS, the I # 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. (For more details on pinning as a concept, [see this guide](/how-to/pin-files).) +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 pinning →](/how-to/pin-files). If you've got just one local IPFS node, and it's always running, local pinning may be all you need to insure 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: From acdbde92dc58cb76d5e2947ab4e619f56433a57f Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:37:53 -0700 Subject: [PATCH 11/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 69e1e1681..dd97f13b9 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -47,7 +47,7 @@ In the next screen, you’ll be asked for a few other details: ![Details modals for adding a new pinning service or a new custom pinning service in Desktop/Web UI](https://user-images.githubusercontent.com/1507828/102558910-ca15f300-408b-11eb-9fe3-742186c077c7.png) -After you hit “Save”, you’ll see your new pinning service added to the “Pinning Services” section of your Settings screen. +After you hit **Save**, you’ll see your new pinning service added to the **Pinning Services** section of your **Settings** screen. ![Desktop/Web UI Settings screen with a new pinning service added](https://user-images.githubusercontent.com/1507828/102558530-db123480-408a-11eb-9e3b-58bbd59b2880.png) From a5b41fd87c5c7fd274d08b0641c3f100a59b479a Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:38:05 -0700 Subject: [PATCH 12/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index dd97f13b9..a8e66af48 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -53,7 +53,7 @@ After you hit **Save**, you’ll see your new pinning service added to the **Pin #### 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”: +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**: ![Desktop/Web UI Files screen with the action menu open and "Set pinning" visible](https://user-images.githubusercontent.com/1507828/102558546-e6656000-408a-11eb-97b8-5fdb060602d2.png) From 1fed18c163e12faac6481d14c3558538832939be Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:38:20 -0700 Subject: [PATCH 13/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index a8e66af48..69f39a4c0 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -69,9 +69,9 @@ To add a new pinning service, use the following command: ipfs pin remote service add nickname https://api.mypinningservice.com/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://api.mypinningservice.com/endpoint` is the endpoint supplied to you by the pinning service (check its documentation for more info) -- `myAccessToken` is the unique token provided to you by the pinning service (check its documentation for more info) +- `nickname` is a unique name for this particular instantiation of a pinning service. TThis can be helpful if, for example, you want to add two accounts from the same service. +- `https://api.mypinningservice.com/endpoint` is the endpoint supplied to you by the pinning service. Check the service's documentation for more info. +- `myAccessToken` is the unique token provided to you by the pinning service. Check the service's documentation for more info. #### Using a pinning service From 8a34606200891b5b6a41583d6b2c34d17ca5bf32 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:38:29 -0700 Subject: [PATCH 14/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 69f39a4c0..3bb90bafb 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -105,7 +105,7 @@ ipfs pin remote --help As noted above, you aren't limited to adding the remote pinning services listed in the Settings screen of Desktop/Web UI. Any remote pinning service that uses 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 +- 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 From 95a06b54f661d55b3a1512bb792155bbd49bd45b Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:38:35 -0700 Subject: [PATCH 15/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 3bb90bafb..77e940795 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -106,8 +106,8 @@ ipfs pin remote --help As noted above, you aren't limited to adding the remote pinning services listed in the Settings screen of Desktop/Web UI. Any remote pinning service that uses 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 +- 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 IPFS Desktop/Web UI and the IPFS CLI. 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! From a11d0ba348c74d7f48a5c07d3e96dbf800c21c4f Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:38:54 -0700 Subject: [PATCH 16/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 77e940795..bb09882a7 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -7,7 +7,7 @@ description: Learn how to use or create remote pinning services with IPFS, the I 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 pinning →](/how-to/pin-files). -If you've got just one local IPFS node, and it's always running, local pinning may be all you need to insure 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: +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 From 620dd58031a848bac098fa445d0e587ae2914046 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:39:10 -0700 Subject: [PATCH 17/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index bb09882a7..77f586b13 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -10,9 +10,9 @@ Depending on how you use IPFS, you might find it helpful to use a **remote pinni 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 +- 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 (examples of these 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. From a8a42539dcb9438083cd2f8f6660a1871518bd67 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:41:45 -0700 Subject: [PATCH 18/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 77f586b13..9a51a7b84 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -14,7 +14,7 @@ If you've got just one local IPFS node that's always running, local pinning may - 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 (examples of these 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. +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 [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) specification — because those pinning services are supported within IPFS itself via the command line, [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), and the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui). And, if you're interested in creating your own pinning service for your own personal or shared use, you can directly integrate it with IPFS Desktop/Web UI and the IPFS CLI by using the IPFS Pinning Service API. From 6f18bffb320990a40b55ac073c4a9975739a6dc4 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:42:04 -0700 Subject: [PATCH 19/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 9a51a7b84..294b23f9a 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -16,7 +16,7 @@ If you've got just one local IPFS node that's always running, local pinning may 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 [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) specification — because those pinning services are supported within IPFS itself via the command line, [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), and the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui). And, if you're interested in creating your own pinning service for your own personal or shared use, you can directly integrate it with IPFS Desktop/Web UI and the IPFS CLI by using the IPFS Pinning Service API. +However, you don't need to learn new commands or tools if your pinning service of choice supports the [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) specification — because those pinning services are supported within IPFS itself through the command line, [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), and the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui). And, if you're interested in creating your own pinning service for your own personal or shared use, you can directly integrate it with IPFS Desktop/Web UI and the IPFS CLI by using the IPFS Pinning Service API. As of January 2021, [Pinata](https://pinata.cloud/) supports the IPFS Pinning Service API, with more pinning services on the way! From 21c9db404c4d90446d47d20d3b42507fbe43e426 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:42:31 -0700 Subject: [PATCH 20/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 294b23f9a..c27a17dc5 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -22,7 +22,7 @@ As of January 2021, [Pinata](https://pinata.cloud/) supports the IPFS Pinning Se ## 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 (you can do this by signing up directly with the service itself). Once you're got an account, follow these steps to add and use it: +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: ### IPFS Desktop or IPFS Web UI From 758e5ef520cc9c30aced54dbf1ba470906ecd468 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:42:48 -0700 Subject: [PATCH 21/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index c27a17dc5..cf7a50154 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -43,7 +43,7 @@ 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 +- 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. ![Details modals for adding a new pinning service or a new custom pinning service in Desktop/Web UI](https://user-images.githubusercontent.com/1507828/102558910-ca15f300-408b-11eb-9fe3-742186c077c7.png) From a1968522cae925541efcb5ddca920dad1b38e6de Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:43:03 -0700 Subject: [PATCH 22/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index cf7a50154..5520c8e45 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -30,7 +30,7 @@ You can add your favorite pinning service(s) to IPFS Desktop/Web UI directly, en #### 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: +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: ![The Desktop/Web UI Settings screen, ready for adding a new pinning service](https://user-images.githubusercontent.com/1507828/102558464-b0c07700-408a-11eb-8ae4-cd30e3ce81fd.png) From 512340ef89fdc1bd19f41ce4c11faaefd1bc4931 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:43:40 -0700 Subject: [PATCH 23/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 5520c8e45..4365e753c 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -34,7 +34,7 @@ To add a new pinning service, open up IPFS Desktop or Web UI, navigate to the ** ![The Desktop/Web UI Settings screen, ready for adding a new pinning service](https://user-images.githubusercontent.com/1507828/102558464-b0c07700-408a-11eb-8ae4-cd30e3ce81fd.png) -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. +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. ![Desktop/Web UI modal for selecting a pinning service to add](https://user-images.githubusercontent.com/1507828/102558471-b918b200-408a-11eb-9a28-b06d03f99121.png) From 457296c3f03b22026354a83eb9e2af6b0093d579 Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:44:02 -0700 Subject: [PATCH 24/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 4365e753c..2e2aa2fef 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -40,7 +40,7 @@ Then, select your chosen pinning service from the modal that pops up. If the pin 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) +- 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. From 702715ec80a221aca41a3a7fba2205ce8a12fd8f Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:44:33 -0700 Subject: [PATCH 25/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 2e2aa2fef..ea4f7a8e7 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -41,7 +41,7 @@ Then, select your chosen pinning service from the modal that pops up. If the pin 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!)_ +- 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. From 9feee4d1ed2c7135438e69183a2a0bc7e166b2ad Mon Sep 17 00:00:00 2001 From: Jessica Schilling Date: Fri, 18 Dec 2020 11:44:47 -0700 Subject: [PATCH 26/28] Update docs/how-to/work-with-pinning-services.md Co-authored-by: Johnny <9611008+johnnymatthews@users.noreply.github.com> --- docs/how-to/work-with-pinning-services.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index ea4f7a8e7..5ccf5b177 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -42,7 +42,7 @@ 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) +- 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. ![Details modals for adding a new pinning service or a new custom pinning service in Desktop/Web UI](https://user-images.githubusercontent.com/1507828/102558910-ca15f300-408b-11eb-9fe3-742186c077c7.png) From cb629c73dcc9dc33e042957a484dff828f87d26a Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 18 Feb 2021 00:39:08 +0100 Subject: [PATCH 27/28] refactor: hide GUI, prioritize CLI --- docs/how-to/pin-files.md | 10 ++-- docs/how-to/work-with-pinning-services.md | 56 ++++++++++++++--------- 2 files changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index aa950b817..a91912b81 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -8,7 +8,7 @@ description: Learn how to pin files in IPFS in order to keep your files and othe Pinning is a very important concept in IPFS. IPFS semantics try to make it feel like every single object is local — there is no "retrieve this file for me from a remote server", just `ipfs cat` or `ipfs get`, which act the same way no matter where the actual object is located. -While this is nice, sometimes you want to be able to control what you keep around. **Pinning** is the mechanism that allows you to tell IPFS to always keep a given object somewhere — the default being your local node, though this can be different if you use a [third-party remote pinning service](#using-a-pinning-service). IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any IPFS operation on it, but these objects may get garbage-collected regularly. To prevent that garbage collection, simply pin the hash you care about. Objects added through `ipfs add` are pinned recursively by default. +While this is nice, sometimes you want to be able to control what you keep around. **Pinning** is the mechanism that allows you to tell IPFS to always keep a given object somewhere — the default being your local node, though this can be different if you use a [third-party remote pinning service](#using-a-pinning-service). IPFS has a fairly aggressive caching mechanism that will keep an object local for a short time after you perform any IPFS operation on it, but these objects may get garbage-collected regularly. To prevent that garbage collection, simply pin the CID you care about, or add it to [MFS](/concepts/file-systems/#mutable-file-system-mfs). Objects added through `ipfs add` are pinned recursively by default. Things in MFS are not pinned by default, but are protected from garbage-collection, so one can think about MFS as a mechanism for implicit pinning. Let's look at this example to explore pinning to your local IPFS node in a bit more depth: @@ -51,6 +51,10 @@ All the information above assumes that you're pinning items locally — that is, While you can use a remote pinning service's own GUI, CLI, or other dev tools to manage IPFS files pinned to their service, you can also work directly with pinning services using your local IPFS installation — meaning that you don't need to learn a pinning service's unique API or other tooling. -- The [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) offers a specification that enables developers to integrate any pinning service that supports the spec, using simple, standardized schemas and fields. -- If you use go-ipfs from the command line, you can add your favorite pinning service(s), pin CIDs under human-readable names, get pin statuses, and more straight from the CLI. [Learn how →](/how-to/work-with-pinning-services/) +- The [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) offers a specification that enables developers to integrate any pinning service that supports the spec, or create their own. Thanks to the OpenAPI spec format, both clients and servers can be [generated](https://github.com/ipfs/pinning-services-api-spec#code-generation) from the YAML spec file. + +- If you use go-ipfs 0.8+ from the command line, you have access to `ipfs pin remote` commands: the porcelain client for interacting with Pinning Service APIs. Add your favorite pinning service(s), pin CIDs under human-readable names, get pin statuses, and more straight from the CLI. [Learn how →](/how-to/work-with-pinning-services/) + + diff --git a/docs/how-to/work-with-pinning-services.md b/docs/how-to/work-with-pinning-services.md index 5ccf5b177..af1956b1d 100644 --- a/docs/how-to/work-with-pinning-services.md +++ b/docs/how-to/work-with-pinning-services.md @@ -5,25 +5,27 @@ description: Learn how to use or create remote pinning services with IPFS, the I # 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 pinning →](/how-to/pin-files). +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 +- 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 [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) specification — because those pinning services are supported within IPFS itself through the command line, [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop), and the [IPFS Web UI](https://github.com/ipfs-shipyard/ipfs-webui). And, if you're interested in creating your own pinning service for your own personal or shared use, you can directly integrate it with IPFS Desktop/Web UI and the IPFS CLI by using the IPFS Pinning Service API. +However, you don't need to learn new commands or tools if your pinning service of choice supports 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, with more pinning services on the way! +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: + + ### IPFS CLI -In addition to integrating your favorite pinning service into IPFS Desktop or Web UI, you can also use it directly from the command line using the `ipfs` command. +Command line users benefit from `ipfs pin remote` commands, which provide porcelain that simplifies remote pinning operations. 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: -```bash -ipfs pin remote service add nickname https://api.mypinningservice.com/endpoint myAccessToken +```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. TThis can be helpful if, for example, you want to add two accounts from the same service. -- `https://api.mypinningservice.com/endpoint` is the endpoint supplied to you by the pinning service. Check the service's documentation for more info. -- `myAccessToken` is the unique token provided to you by the pinning service. Check the service's documentation for more info. +- `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 @@ -79,36 +83,46 @@ Here are a few CLI commands to get you started. In all examples, replace `nickna To pin a CID under under a human-readable name: -```bash -ipfs pin remote add --service=nickname --name=war-and-peace.txt bafybeib32tuqzs2wrc52rdt56cz73sqe3qu2deqdudssspnu4gbezmhig4 +```console +$ ipfs pin remote add --service=nickname --name=war-and-peace.txt bafybeib32tuqzs2wrc52rdt56cz73sqe3qu2deqdudssspnu4gbezmhig4 ``` To list successful pins: -```bash -ipfs pin remote ls --service=nickname +```console +$ ipfs pin remote ls --service=nickname ``` -To list pending pins: +To list all "pending" pins: -```bash -ipfs pin remote ls --service=nickname --status=queued,pinning,failed +```console +$ ipfs pin remote ls --service=nickname --status=queued,pinning,failed ``` For more commands and general help: -```bash -ipfs pin remote --help +```console +$ ipfs pin remote --help ``` ## Create your own pinning service -As noted above, you aren't limited to adding the remote pinning services listed in the Settings screen of Desktop/Web UI. Any remote pinning service that uses 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: +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 IPFS Desktop/Web UI and the IPFS CLI. 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! +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! +::: + + From 5896c56a6cea9dc027650b5361ef6e1e68e41b91 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 18 Feb 2021 14:17:26 +0100 Subject: [PATCH 28/28] style: remove porcelain, tweak style --- docs/how-to/pin-files.md | 2 +- docs/how-to/work-with-pinning-services.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to/pin-files.md b/docs/how-to/pin-files.md index a91912b81..a702ee339 100644 --- a/docs/how-to/pin-files.md +++ b/docs/how-to/pin-files.md @@ -53,7 +53,7 @@ While you can use a remote pinning service's own GUI, CLI, or other dev tools to - The [IPFS Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/) offers a specification that enables developers to integrate any pinning service that supports the spec, or create their own. Thanks to the OpenAPI spec format, both clients and servers can be [generated](https://github.com/ipfs/pinning-services-api-spec#code-generation) from the YAML spec file. -- If you use go-ipfs 0.8+ from the command line, you have access to `ipfs pin remote` commands: the porcelain client for interacting with Pinning Service APIs. Add your favorite pinning service(s), pin CIDs under human-readable names, get pin statuses, and more straight from the CLI. [Learn how →](/how-to/work-with-pinning-services/) +- If you use go-ipfs 0.8+ from the command line, you have access to `ipfs pin remote` commands acting as a client for interacting with pinning service APIs. Add your favorite pinning service(s), pin CIDs under human-readable names, get pin statuses, and more, straight from the CLI. [Learn how →](/how-to/work-with-pinning-services/)