Skip to content

Commit 7438a5b

Browse files
committed
Add fetch with a node section
1 parent 8a14360 commit 7438a5b

File tree

1 file changed

+62
-8
lines changed

1 file changed

+62
-8
lines changed

docs/quickstart/publish.md

Lines changed: 62 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,20 @@ In this quickstart guide, you will learn about [pinning services](../concepts/pe
99

1010
> **Note:** The web3.storage pinning service was chosen purely for demonstration purposes, and is one of many [pinning services](../concepts/persistence.md#pinning-in-context) you can choose from. While each pinning services has different SDKs and APIs, their fundamental role is the same - to store files and make them available to the IPFS network. In fact, one of the main benefits of IPFS is that files can be pinned to multiple pinning services, thereby reducing vendor lock-in.
1111
12+
## Contents <!-- omit from toc -->
13+
14+
- [What is pinning?](#what-is-pinning)
15+
- [Prerequisites](#prerequisites)
16+
- [Uploading and pinning a file](#uploading-and-pinning-a-file)
17+
- [What's a CID?](#whats-a-cid)
18+
- [The lifecycle of data in IPFS](#the-lifecycle-of-data-in-ipfs)
19+
- [Fetching your published CID](#fetching-your-published-cid)
20+
- [Verified vs. trusted CID retrieval](#verified-vs-trusted-cid-retrieval)
21+
- [Using an IPFS Node](#using-an-ipfs-node)
22+
- [Fetching the CID with an IPFS Gateway](#fetching-the-cid-with-an-ipfs-gateway)
23+
- [Conclusion](#conclusion)
24+
- [Next steps](#next-steps)
25+
1226
## What is pinning?
1327

1428
Pinning a file to IPFS is how content is published to IPFS. Any given file represented by a CID can be pinned to multiple IPFS nodes to increase the redundancy and resilience of the file on the network. Pinning services are like hosting services that run an IPFS node for you and ensure that your files are available to the IPFS network.
@@ -66,6 +80,8 @@ bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4
6680

6781
You can now share the CID and anyone should be able to fetch it.
6882

83+
To dive deeper into the anatomy of the CID, check out the [CID inspector](https://cid.ipfs.tech/#bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)
84+
6985
> **Note:** the transformation into a content-addressable representation is a local operation that doesn't require any network connectivity. With web3.storage, this transformation happens on the client-side (in the browser.)
7086
7187
## The lifecycle of data in IPFS
@@ -84,24 +100,62 @@ To understand what happens when you pin a file, it's helpful to understand the l
84100

85101
Note that once the CID is replicated, it is typically advertised by default, even if it isn't explicitly pinned.
86102

87-
## Fetching your published file
103+
## Fetching your published CID
88104

89105
Now that the file is published and you have a CID, you will learn how it can be fetched from the IPFS network.
90106

91-
There are two primary ways to fetch files published with IPFS:
107+
There are two primary ways to retrieve files (and directories) published with IPFS:
108+
109+
- [**IPFS node**](/concepts/nodes/) by installing one of the IPFS implementations, e.g. [Kubo](/concepts/nodes/#kubo) on your computer which allows you to fetch and verify CIDs from other nodes in the IPFS network.
110+
- [**IPFS Gateway**](/concepts/ipfs-gateway/) HTTP interface to the IPFS network that allows fetching data from IPFS with HTTP. Pinning services typically offer an IPFS gateway as a way to easily retrieve your CIDs.
111+
112+
The first option allows you to speak the suit of IPFS protocols. The latter serves as a bridge in situations where you might be constrained to using HTTP, such as in web apps where your app users may not be running an IPFS node.
113+
114+
IPFS Gateways, in their most basic form, are typically IPFS nodes that are hosted by someone else and expose an HTTP interface to fetch CIDs:
115+
116+
![gateway diagram](./images/gateway.png)
117+
118+
### Verified vs. trusted CID retrieval
119+
120+
Another thing to consider when considering the two approaches is _verification_. By default, an IPFS node hashes each block and ensures that when the file is constructed from the blocks (into a Merkle DAG), it results in the CID you requested. However, with IPFS Gateways, verification is optional.
121+
122+
Non-verified retrieval is also commonly referred to as trusted retrieval because you're trusting the gateway to return the correct response without calculating the hash.
123+
124+
While verification is almost always recommended, in reality, there are situations where trusted retrieval is the pragmatic choice, like when embedding images on a website.
92125

93-
- **IPFS node** by installing one of the IPFS implementations, e.g. [Kubo](/concepts/nodes/#kubo)
94-
- [**IPFS Gateway**](/concepts/ipfs-gateway/) HTTP interface to the IPFS network that allows fetching data from IPFS with HTTP.
126+
### Fetching the CID with Kubo
95127

96-
The first option allows you to speak the native IPFS protocol. The latter serves as a bridge in situations where you might be constrained to using HTTP, such as in web apps where your app users may not be running an IPFS node.
128+
To fetch the CID with [Kubo](/install/command-line/), you need to first ensure that the Kubo daemon is installed and running:
97129

98-
### Using an IPFS Node
130+
```bash
131+
$ ipfs daemon
132+
```
133+
134+
To fetch the file, run the [`ipfs get [CID]`](/reference/kubo/cli/#ipfs-get) command:
135+
136+
```bash
137+
$ ipfs get bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4
138+
```
139+
140+
The output should look as follows:
99141

100-
Using a Kubo
142+
```bash
143+
Saving file(s) to bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4
144+
647.61 KiB / 647.61 KiB [========================================================================================================================] 100.00% 0s
145+
```
146+
147+
A new folder with the same name as the CID was created:
148+
149+
```bash
150+
$ ls bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4/
151+
welcome-to-IPFS.jpg
152+
```
153+
154+
Congratulations, you have successfully fetched the CID.
101155

102156
### Fetching the CID with an IPFS Gateway
103157

104-
![gateway diagram](./images/gateway.png)
158+
TODO
105159

106160
- [https://ipfs.io/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://ipfs.io/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)
107161
- [https://cloudflare-ipfs.com/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://cloudflare-ipfs.com/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)

0 commit comments

Comments
 (0)