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
Copy file name to clipboardExpand all lines: docs/quickstart/publish.md
+57-43Lines changed: 57 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,90 +3,104 @@ title: 'Publish a file to IPFS'
3
3
description: 'learn about pinning services and the lifecycle of content-addressed data in IPFS by pinning a file to the IPFS network'
4
4
---
5
5
6
-
# Publish a file to IPFS
6
+
# Publish a file to IPFS with a pinning service
7
7
8
-
In this quickstart guide, you will learn about **pinning services** and the lifecycle of content-addressed data in IPFS by pinning a file to the IPFS network. 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 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.
9
9
10
-
Pinning a file to IPFS is how content is published to IPFS. Any given file can be pinned to multiple IPFS nodes to increase the redundancy and resilience of a file on the network.
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
12
-
To do this, you will use a [pinning service](../concepts/persistence.md#pinning-in-context) called [web3.storage](https://web3.storage/) for this. Pinning services are like hosting services that run an IPFS node for you and ensure your files are available to the IPFS network.
12
+
## What is pinning?
13
13
14
-
> **Note:** web3.storage was chosen purely for demonstration purposes, and is one of many [pinning services](../concepts/persistence.md#pinning-in-context) you can chose from. While pinning services have different SDKs and APIs, their fundemental role is the same: to store files and make them available to the IPFS network.
15
-
16
-
In this guide, you will use the web3.storage UI to upload the file. If you prefer uploading with JavaScript or Go, check out the [Web3.storage docs](https://web3.storage/docs/how-tos/store/). Alternatively,with [Filebase](https://filebase.com/) is a pinning service that offers an AWS S3 compatible API for pinning, so you can use any existing tooling
14
+
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.
17
15
16
+
:::callout
17
+
It's worth noting that 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.
18
+
:::
18
19
## Prerequisites
19
20
20
21
- A free [web3.storage](https://web3.storage/) account.
21
22
- The [following image](/images/welcome-to-IPFS.jpg), downloaded and saved on your computer:
22
23
23
24
24
25
25
-
## 1. Sign in to web3.storage
26
+
## Uploading and pinning a file
26
27
27
-
Start by signing into your account on web3.storage:
1. Upload and pin the file by either dragging the [image file](/images/welcome-to-IPFS.jpg) to the dashed rectangle, or clicking on the dashed rectangle to select the [image](/images/welcome-to-IPFS.jpg) file.
40
41
41
-
## 3. Upload and Pin the file
42
+
Once the file has been successfully uploaded, the following displays:
42
43
43
-
Either drag the [image file](/images/welcome-to-IPFS.jpg) to the dashed rectangle or click on the dashed rectangle to select the [image](/images/welcome-to-IPFS.jpg) file.
48
49
49
-
If you close the upload tab you should also be able to see a shortened Content Identifier ([CID](../concepts/content-addressing.md)) of the uploaded image, `bafyb...d32wm3q4`:
50
+
Congratulations, you have successfully **pinned** a file to IPFS! 🎉
50
51
51
-
52
+
Let's unpack what just happened, by looking at CIDs, and how they fits into the lifecycle of data in IPFS
52
53
53
-
Congratulations, you have successfully **pinned** a file to IPFS!
54
+
## What's a CID?
54
55
55
-
### What's a CID
56
+
In IPFS, every file and directory is identified with a Content Identifier ([CID](../concepts/content-addressing.md)). The generated CID serves as the **permanent address** of the file and can be used by anyone to find it on the IPFS network.
56
57
57
-
Let's unpack what just happened. In IPFS, every file and directory is identified with a CID. The generated CID serves as the permanent address of the file and can be used by anyone to find it on the IPFS network.
58
+
For a file to be published to IPFS (like the image used in this guide), it has to be transformed into a content-addressable representation which generates a CID by hashing the guts of the file
58
59
59
-
The CID for your uploaded image is:`bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4`
When you uploaded and pinned the file to web3.storage you performed two actions:
66
+
You can now share the CID and anyone should be able to fetch it.
64
67
65
-
1.**Representing:** The file was transformed into a content-addressable representation known as a [Merkle DAG](../concepts/merkle-dag.md). Don't worry about what that means, besides that it makes the files and directories **content-addressable** with CIDs by chunking files into smaller chunks and calculating their hashes.
66
-
2.**providing:** The content-addressable representation of the file was persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
68
+
:::callout
69
+
Note that the transformation into a content-addressable representation can be a local operation that doesn't require any network connectivity. With web3.storage, this transformation happens on the client-side (in the browser.)
70
+
:::
67
71
68
-
## Fetching the CID from multiple gateways
72
+
## The lifecycle of data in IPFS
69
73
70
-
IPFS Gateways are like bridges that give access to the IPFS Network using HTTP.
74
+
To understand what happened when you pinned the file, it's helpful to understand the lifecycle of data in IPFS, which can be summarised as follows:
71
75
72
-
76
+
1.**Content-addressable representation**: The file is transformed into a content-addressable representation known as a [Merkle DAG](../concepts/merkle-dag.md). 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** and calculating their hashes.
77
+
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 retrieveable, pinning typically refers to two things:
78
+
-**Advertising:** Making it discoverable to the IPFS network by advertising a record linking between the CID and the server's IP address to the network. This advertising stage is a continuous process that repeats.
79
+
-**Providing:** The content-addressable representation of the file is persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
- IPFS node that implements the IPFS suite of protocols
87
+
- IPFS gateway: an IPFS node that provides an HTTP interface to the IPFS network and bridges between IPFS and HTTP.
88
+
89
+
### Using an IPFS Node
79
90
80
-
- Representing
81
-
- Providing/Advertising
82
-
- Fetching
83
-
- Pinning
84
-
- Deleting
85
91
86
-
> Note: Note that the transformation into a content-addressable representation can be a local operation that doesn't require any network connectivity. With web3.storage this happens on the client-side in the browser but it's also common .
87
92
88
-
This means that you can now share the CID and anyone should be able to fetch it.
- If you prefer uploading with JavaScript or Go, check out the [Web3.storage docs](https://web3.storage/docs/how-tos/store/).
106
+
- 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