You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The lifecycle of data in IPFS can be summarised as follows:
9
+
10
+
1.**Content-addressable representation**: The file is transformed into a content-addressable representation with a CID. The basic idea is that this representation makes files and directories **content-addressable** via CIDs by chunking files into smaller blocks, calculating their hashes, and constructing a [Merkle DAG](./merkle-dag.md).
11
+
2.**Pinning:** refers to the stage where the blocks of the CID are saved on an IPFS node (or pinning service) and made retrievable to the network. Since saving is not enough for the CID to be retrievable, pinning typically refers to two things:
12
+
-**Advertising:** Making each CID discoverable to the IPFS network by advertising a record linking between the CID and the server's IP address to the [DHT](./dht.md). This advertising stage is a continuous process that repeats typically every 12 hours. The term **publishing** is also commonly used to refer to this step.
13
+
-**Providing:** The content-addressable representation of the CID is persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
14
+
3.**Retrieval:** refers to when an IPFS node fetches the blocks of the CID and constructs the Merkle DAG. This usually involves several steps:
15
+
-**Block fetching:** An IPFS node fetches the blocks of the Merkle DAG (of the file or folder) from providers.
16
+
-**Verifying** the IPFS node verifies the blocks fetched by hashing them and ensuring the resulting hash is correct. Note that blocks can come from any node in the network and this type of retrieval is _trustless_.
17
+
-**Local access:** once all the blocks are present, the Merkle DAG can be constructed making the file or directory underlying the CID successfully replicated and accessible.
18
+
4.**Deleting:** refers to the deletion of a CID from a node. Deletion is always a local operation. If a CID has been replicated by other nodes, it will continue to be available on the IPFS network.
19
+
20
+
> **Note:** once the CID is replicated by another node, it is typically advertised by default, even if it isn't explicitly pinned.
21
+
22
+
Learn more about the lifecycle of data in IPFS in the following video:
Copy file name to clipboardExpand all lines: docs/install/README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,9 @@ description: There are several different ways you can install and interact with
7
7
8
8
IPFS is a collection of protocols, packages, and specifications that allow computers to send and receive data. Because of this, users can interact with and use IPFS in many different ways. A developer building network applications will use a different set of tools to interact with IPFS than than someone who wants to store files on IPFS. Pick the one that best suits what you're here to do.
9
9
10
-
## Publish files to IPFS
10
+
## Publish files with a pinning service
11
11
12
-
Are you wanting to quickly and easily publish content to IPFS without using complex tools? See the [Publish to IPFS quickstart](../quickstart/publish.md), where you'll learn about pinning services and the lifecycle of content-addressed data in IPFS by publishing and pinning a file to the IPFS network.
12
+
Do you want to quickly and easily publish content with IPFS without complex tools? See the [Publish with IPFS quickstart](../quickstart/publish.md), where you'll learn how to use pinning services to pin files to the IPFS network.
description: 'learn about pinning services and the lifecycle of content-addressed data in IPFS by pinning a file to the IPFS network'
2
+
title: 'Publishing a file with IPFS using a pinning service'
3
+
description: 'learn how to publish content with IPFS by pinning a file to a pinning service'
4
4
---
5
5
6
-
# Publish a file to IPFS with a pinning service
6
+
# Publish a file with IPFS
7
7
8
-
In this quickstart guide, you will learn about [pinning services](../concepts/persistence.md#pinning-in-context) and the lifecycle of content-addressed data in IPFS by pinning a file to the IPFS network using a pinning service called [web3.storage](https://web3.storage/). By the end of this guide, you should have a better understanding of how content addressing and CIDs work from a high level.
8
+
In this quickstart guide, you will learn about [pinning services](../concepts/persistence.md#pinning-in-context) and how to use them to publish content-addressed data with IPFS. To do so, you will upload the file to a pinning service called [web3.storage](https://web3.storage/). By the end of this guide, you should have a better understanding of how content addressing and CIDs work from a high level.
9
9
10
10
> **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.
11
11
@@ -15,17 +15,17 @@ In this quickstart guide, you will learn about [pinning services](../concepts/pe
15
15
-[Prerequisites](#prerequisites)
16
16
-[Uploading and pinning a file](#uploading-and-pinning-a-file)
17
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)
18
+
-[Summary and next steps](#summary-and-next-steps)
25
19
26
20
## What is pinning?
27
21
28
-
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.
22
+
Pinning refers to the process of ensuring that a particular piece of content is retrievable with IPFS. In other words, pinning is equivalent to storing a file on a computer or server that is connected to the internet, thereby making it available to the rest of the IPFS network.
23
+
24
+
Pinning can be done at various levels, from individual files to entire directories that are addressed by a CID. You can also pin CIDs to multiple IPFS nodes to increase the redundancy and resilience of the file on the network.
25
+
26
+
### Pinning services
27
+
28
+
[Pinning services](../concepts/persistence/#pinning-services) are like hosting services that run an IPFS node for you and ensure that your files are available to the IPFS network.
29
29
30
30
:::callout
31
31
Data pinned to the IPFS network is public by default and retrievable by anyone. Make sure to avoid publishing private data or take the necessary measures to adequately encrypt it before publishing.
@@ -64,106 +64,47 @@ Data pinned to the IPFS network is public by default and retrievable by anyone.
64
64
65
65
Congratulations, you have successfully **pinned** a file to IPFS! 🎉
66
66
67
-
Let's unpack what just happened, by looking at CIDs, and how they fits into the lifecycle of data in IPFS
67
+
Let's unpack what just happened, by looking at CIDs.
68
68
69
69
## What's a CID?
70
70
71
71
In IPFS, every file and directory is identified with a Content Identifier ([CID](../concepts/content-addressing.md)). The CID serves as the **permanent address** of the file and can be used by anyone to find it on the IPFS network.
72
72
73
-
When a file is published to IPFS (like the image used in this guide), it's first transformed into a content-addressable representation by which the file is split into smaller chunks (if above ~1MB) which are linked and hashed to produce the CID.
73
+
When a file is first added to an IPFS node (like the image used in this guide), it's first transformed into a content-addressable representation by which the file is split into smaller chunks (if above ~1MB) which are linked and hashed to produce the CID.
You can now share the CID and anyone should be able to fetch it.
81
+
You can now share the CID with anyone and they can fetch the file using IPFS.
82
82
83
83
To dive deeper into the anatomy of the CID, check out the [CID inspector](https://cid.ipfs.tech/#bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)
84
84
85
85
> **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.)
86
86
87
-
## The lifecycle of data in IPFS
88
-
89
-
To understand what happens when you pin a file, it's helpful to understand the lifecycle of data in IPFS, which can be summarised as follows:
90
-
91
-
1.**Content-addressable representation**: The file is transformed into a content-addressable representation with a CID. For this guide, the full details are not important. The basic idea is that this representation makes files and directories **content-addressable** via CIDs by chunking files into smaller blocks\*\*, calculating their hashes, and constructing a [Merkle DAG](../concepts/merkle-dag.md).
92
-
2.**Pinning:** refers to the stage where the blocks of the CID are saved on an IPFS node (or multiple nodes), in this case, web3.storage. Since saving is not enough for the CID to be retrievable, pinning typically refers to two things:
93
-
-**Advertising:** Making it discoverable to the IPFS network by advertising a record linking between the CID and the server's IP address to <VueCustomTooltiplabel="Distributed Hash Table: a decentralized data store that maps data based on key-value pairs."underlinedmultilineis-left>the DHT</VueCustomTooltip>. This advertising stage is a continuous process that repeats typically every 12 hours.
94
-
-**Providing:** The content-addressable representation of the CID is persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
95
-
3.**Retrieval:** refers to when an IPFS node fetches the blocks of the CID and constructs the Merkle DAG. This usually involves several steps:
96
-
-**Block fetching:** An IPFS node fetches the blocks of the Merkle DAG (of the file or folder) from providers.
97
-
-**Verifying** the IPFS node verifies the blocks fetched by hashing them and ensuring the resulting hash is correct. Note that blocks can come from any node in the network and this type of retrieval is _trustless_.
98
-
-**File access:** once all the blocks are present, the Merkle DAG can be constructed making the CID successfully replicated and accessible.
99
-
4.**Deleting:** refers to the deletion of a CID from a node. Deletion is always a local operation. If a CID has been replicated by other nodes, it will continue to be available on the IPFS network.
100
-
101
-
Note that once the CID is replicated, it is typically advertised by default, even if it isn't explicitly pinned.
102
-
103
-
## Fetching your published CID
104
-
105
-
Now that the file is published and you have a CID, you will learn how it can be fetched from the IPFS network.
106
-
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
-
87
+
## Retrieving with a gateway
117
88
118
-
### Verified vs. trusted CID retrieval
89
+
Now that your file is pinned to a pinning service, you will fetch it using an IPFS gateway. An [**IPFS Gateway**](/concepts/ipfs-gateway/) is an HTTP interface that serves as a bridge to the IPFS network. In other words, it allows fetching CIDs from IPFS with HTTP.
119
90
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.
91
+
Pinning services typically offer an IPFS gateway as a way to easily retrieve your CIDs, for example, Web3.storage operates the [w3s.link](https://w3s.link) gateway, with which you can retrieve the uploaded CID.
121
92
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.
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.
125
-
126
-
### Fetching the CID with Kubo
127
-
128
-
To fetch the CID with [Kubo](/install/command-line/), you need to first ensure that the Kubo daemon is installed and running:
129
-
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:
141
-
142
-
```bash
143
-
Saving file(s) to bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4
A new folder with the same name as the CID was created:
148
-
149
-
```bash
150
-
$ ls bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4/
151
-
welcome-to-IPFS.jpg
152
-
```
96
+
> **Note:** When pinning a file to IPFS, the filename is not stored by default. To ensure the filename is retained, it's common to wrap the file in a directory. In such instances, both the file and the directory will have unique CIDs. Web3.storage wraps files in a directory by default, which is why you see a directory listing with the file `welcome-to-IPFS.jpg` followed by a shorthand CID: `bafk…beom` of the file.
153
97
154
-
Congratulations, you have successfully fetched the CID.
98
+
## Summary and next steps
155
99
156
-
### Fetching the CID with an IPFS Gateway
100
+
In this quickstart guide, you learned about [pinning services](../concepts/persistence.md#pinning-in-context), and how to use them to publish content-addressed data with IPFS. You also learned how CIDs address files and directories in IPFS by uploading a file to a pinning service called [web3.storage](https://web3.storage/).
157
101
158
-
TODO
102
+
Pinning services provide a convenient alternative to running IPFS nodes and infrastructure. However, the two are not mutually exclusive; you can combine a pinning service with an IPFS node on your computer to increase the resilience of your CIDs.
Check out [the lifecycle of data in IPFS](../concepts/lifecycle.md) to learn more about how publishing by pinning fits into the full lifecycle of data in IPFS.
163
105
164
-
## Conclusion
106
+
As a next step, try fetching the pinned file, by following the [retrieval quickstart](./retrieve.md).
165
107
166
-
## Next steps
108
+
If you prefer programmatically uploading with JavaScript or Go, check out the [Web3.storage docs](https://web3.storage/docs/how-tos/store/).
167
109
168
-
- If you prefer uploading with JavaScript or Go, check out the [Web3.storage docs](https://web3.storage/docs/how-tos/store/).
169
-
- Try out [Filebase](https://filebase.com/), a pinning service that offers an [AWS S3-compatible API for pinning](https://docs.filebase.com/getting-started/s3-api-getting-started-guide), so you can use any S3-compatible SDK, e.g. [aws-sdk](https://www.npmjs.com/package/aws-sdk), and [many](https://github.com/s3tools/s3cmd) more.
110
+
Alternatively, try out [Filebase](https://filebase.com/), a pinning service that offers an [AWS S3-compatible API for pinning](https://docs.filebase.com/getting-started/s3-api-getting-started-guide), so you can use any S3-compatible SDK, e.g. [aws-sdk](https://www.npmjs.com/package/aws-sdk), and [many](https://github.com/s3tools/s3cmd) more.
0 commit comments