Skip to content

chore: cleanup outdated services and old links #2108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/how-to/gateway-best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ If you are running an IPFS node that is also configured as an IPFS gateway, each
- If your node is not reachable because you are behind NAT, see the [NAT configuration](https://docs.ipfs.tech/how-to/nat-configuration/#ipv6) docs.
- Ensure that you are correctly returning HTTP cache headers to the client if the IPFS gateway node is behind a reverse proxy. Pay extra attention to `Etag`, `Cache-Control`, and `Last-Modified headers`. Consider leveraging the list of CIDs in `X-Ipfs-Roots` for smarter HTTP caching strategies.
- Put a CDN like Cloudflare in front of the IPFS gateway.
- Consider enabling the [Accelerated DHT Client](https://github.com/ipfs/go-ipfs/blob/master/docs/experimental-features.md#accelerated-dht-client).
- Consider enabling the [Accelerated DHT Client](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingaccelerateddhtclient).
- Test and monitor your internet connection speed, with a tool like [Speedtest CLI](https://www.speedtest.net/apps/cli).
- Monitor disk I/O and make sure that no other processes are causing disk I/O bottlenecks with a tool like [iotop](https://github.com/Tomas-M/iotop) or [iostat](https://github.com/sysstat/sysstat).

Expand Down
2 changes: 1 addition & 1 deletion docs/how-to/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ With this in mind, if no providers are returned, do the following:

2. Note the value for `LastReprovideDuration`. If it is close to 48 hours, or if you notice a "reprovide taking too long" warning in your `ipfs daemon` output log, select one of the following options, keeping in mind that each has tradeoffs:

- **Enable the [Accelerated DHT Client](https://github.com/ipfs/go-ipfs/blob/master/docs/experimental-features.md#accelerated-dht-client) in Kubo**. This configuration improves content providing times significantly by maintaining more connections to peers and a larger routing table and batching advertising of provider records. However, this performance boost comes at the cost of increased resource consumption, most notably network connections to other peers, and can lead to degraded network performance in home networks.
- **Enable the [Accelerated DHT Client](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingaccelerateddhtclient) in Kubo**. This configuration improves content providing times significantly by maintaining more connections to peers and a larger routing table and batching advertising of provider records. However, this performance boost comes at the cost of increased resource consumption, most notably network connections to other peers, and can lead to degraded network performance in home networks.

- **Change the [Reprovider Strategy](https://github.com/ipfs/kubo/blob/master/docs/config.md#reproviderstrategy) from `all` to either `pinned+mfs` or `roots`.** In both cases, only provider records for explicitly pinned content are advertised. Differences and tradeoffs are noted below:
- The `pinned+mfs` strategy will advertise both the root CIDs and child block CIDs (the entire DAG) of explicitly pinned content and the locally available part of MFS.
Expand Down
6 changes: 5 additions & 1 deletion docs/install/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ Anyone can use IPFS to store files in a _decentralized_ way. The easiest way to

If your browser doesn't support IPFS yet, you can install an IPFS companion extension that will let you view decentralized web content! [Learn more →](./ipfs-companion.md)

### Publish files with a pinning service

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 third-party pinning services to pin and provide files to the IPFS network.

### Deploy static sites to the IPFS network with a GitHub Action

Do you want to quickly and easily automate the deployment of static websites to the IPFS network? See the [Deploy static sites to the IPFS network with GitHub Actions](../how-to/websites-on-ipfs/deploy-github-action.md), where you'll learn how to use [GitHub Actions](https://github.com/ipshipyard/ipfs-deploy-action) to automatically deploy static websites to the IPFS network.
Expand Down Expand Up @@ -53,7 +57,7 @@ To get started with a hands-on example, see [Helia 101](https://github.com/ipfs-
If you are looking for simple [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-like API for use on the web, see [@helia/verified-fetch](https://www.npmjs.com/package/@helia/verified-fetch).
:::

### Boxo SDK for GO
### Boxo SDK for Go

[Boxo](https://github.com/ipfs/boxo#readme) is a set of reference libraries for building IPFS applications and implementations in Go.

Expand Down
2 changes: 1 addition & 1 deletion docs/install/command-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ This reduces daemon overhead on the system but may degrade content discovery and
This section describes how to download and install the Kubo binary from `dist.ipfs.tech` on Windows, MacOS, Linux, FreeBSD and OpenBSD operating systems. The IPFS team publishes the latest, official prebuilt Kubo binaries on the [dist.ipfs.tech website](https://dist.ipfs.tech#kubo). New IPFS Kubo binary releases are automatically shown on the Kubo page on `dist.ipfs.tech`.

:::callout
If you are unable to access [dist.ipfs.tech](https://dist.ipfs.tech#kubo), you can also download Kubo (go-ipfs) from the project's GitHub [releases](https://github.com/ipfs/kubo/releases/latest) page or `/ipns/dist.ipfs.tech` at the [dweb.link](https://dweb.link/ipns/dist.ipfs.tech#kubo) gateway.
If you are unable to access [dist.ipfs.tech](https://dist.ipfs.tech#kubo), you can also download Kubo from the project's GitHub [releases](https://github.com/ipfs/kubo/releases/latest) page or `/ipns/dist.ipfs.tech` at the [dweb.link](https://dweb.link/ipns/dist.ipfs.tech#kubo) gateway.
:::

For installation instructions for your operating system, select the appropriate tab.
Expand Down
Binary file removed docs/quickstart/images/account-console.png
Binary file not shown.
Binary file removed docs/quickstart/images/login-web3-storage.png
Binary file not shown.
Binary file removed docs/quickstart/images/web3-file-after-upload.png
Binary file not shown.
Binary file removed docs/quickstart/images/web3-file-uploaded.png
Binary file not shown.
Binary file removed docs/quickstart/images/web3-upload-button.png
Binary file not shown.
Binary file removed docs/quickstart/images/web3-upload-tab.png
Binary file not shown.
95 changes: 53 additions & 42 deletions docs/quickstart/publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,18 @@

# Publish a file with IPFS
Copy link
Member

@2color 2color Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest we name this pinning to be consistent with the terminology used in the lifecycle page https://docs.ipfs.tech/concepts/lifecycle

(I was the one who named this publishing but I no longer think it's a useful term for this, given that you're working with pinning services).

While at it, perhaps rename the files too.

Suggested change
# Publish a file with IPFS
# Pinning a file with IPFS


:::warning
Some steps of this guide are currently outdated due to [changes with web3.storage](https://blog.web3.storage/posts/the-data-layer-is-here-with-the-new-web3-storage).
:::

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 learn the process, 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.
In this quickstart guide, you will learn about [pinning services](../concepts/persistence.md#pinning-in-context) and how to use their **web interfaces** to publish content with IPFS. By the end of this guide, you should have a better understanding of how content addressing and CIDs work from a high level.

:::callout
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.
If you prefer command-line tools, see [Publish using the command line](./publish_cli.md).
:::

## Contents <!-- omit from toc -->

- [Overview](#overview)
- [Pinning services](#pinning-services)
- [Prerequisites](#prerequisites)
- [Uploading and pinning a file](#uploading-and-pinning-a-file)
- [Upload and pin a file](#upload-and-pin-a-file)
- [CIDs explained](#cids-explained)
- [Retrieving with a gateway](#retrieving-with-a-gateway)
- [Summary and next steps](#summary-and-next-steps)
Expand All @@ -41,44 +37,33 @@

## Prerequisites

- A free [web3.storage](https://web3.storage/) account.
- The [following image](../quickstart/images/welcome-to-IPFS.jpg), downloaded and saved on your computer:
To follow along with this guide, you'll need:

- An account with at least one pinning service (free tier is sufficient):
- [Pinata](https://pinata.cloud/) - Popular IPFS pinning service with simple web interface
- [Filebase](https://filebase.com) - S3-compatible pinning service with web dashboard
- [Storacha](https://storacha.network) - Decentralized storage network
- A sample file to upload, such as the [following image](../quickstart/images/welcome-to-IPFS.jpg):

![image](../quickstart/images/welcome-to-IPFS.jpg)

## Upload and pin a file

1. Sign into your account on web3.storage.

![web3.storage login window](./images/login-web3-storage.png)

1. After logging in, click on **Upload files** to open the upload tab.

![web3.storage upload button](./images/web3-upload-button.png)

1. Upload and pin the file by doing either dragging the [image file](../quickstart/images/welcome-to-IPFS.jpg) to the dashed rectangle labeled **Drag and drop your files here**, or clicking on the dashed rectangle to select the [image](../quickstart/images/welcome-to-IPFS.jpg) file.

![web3.storage upload tab](./images/web3-upload-tab.png)

Once the file has been successfully uploaded, the following displays:

![web3.storage file uploaded](./images/web3-file-uploaded.png)
Choose one of the following pinning services and use their web interface to upload your first file:

If you close the upload tab, you should also be able to see a shortened **Content Identifier (CID)** of the uploaded image, **`bafyb...d32wm3q4`**, similar to the image below:
- **Pinata**: Use the [Pinata App](https://app.pinata.cloud) for a simple drag-and-drop upload experience - see their [quickstart tutorial](https://docs.pinata.cloud/quickstart)
- **Filebase**: Access their web dashboard and follow their [pin your first file guide](https://docs.filebase.com/getting-started/getting-started-guides/pin-your-first-file-to-ipfs)
- **Storacha**: Requires some technical skills, but their [browser upload guide](https://docs.storacha.network/how-to/upload/) may be a useful option if you are developing a web application. You can also visit [console.storacha.network](https://console.storacha.network) for web-based uploads

![file after upload](./images/web3-file-after-upload.png)

Congratulations, you have successfully **pinned** a file to IPFS! 🎉

Let's unpack what just happened, by looking at CIDs.
Each service will provide you with a **CID** (Content Identifier) after uploading your file. Save this CID as you'll use it to retrieve your file in the next sections.

## CIDs explained

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.

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 in which the file is split into smaller chunks (if above ~1MB) which are linked together and hashed to produce the CID.

In this guide, the CID for the uploaded image is:
For example, a CID might look like:

```plaintext
bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4
Expand All @@ -89,31 +74,57 @@
To dive deeper into the anatomy of the CID, check out the [CID inspector](https://cid.ipfs.tech/#bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4)

:::callout
The transformation into a content-addressable representation is a local operation that doesn't require any network connectivity. With web3.storage, this transformation happens client-side (in the browser).
The transformation into a content-addressable representation is a local operation that doesn't require any network connectivity. With many pinning services, this transformation happens client-side (in the browser).
:::

## Retrieving with a gateway

Now that your file is pinned to a pinning service, you will fetch it using an IPFS gateway. An [**IPFS Gateway**](../concepts/ipfs-gateway.md) is an HTTP interface that serves as a bridge to the IPFS network. In other words, it allows you to fetch CIDs from IPFS using HTTP.
Now that your file is pinned to a pinning service, you can fetch it using an IPFS gateway. An [**IPFS Gateway**](../concepts/ipfs-gateway.md) is an HTTP interface that serves as a bridge to the IPFS network. In other words, it allows you to fetch CIDs from IPFS using HTTP in your web browser.

Pinning services typically offer their own IPFS gateways:

### Pinata Gateway
Pinata offers both public and dedicated gateway options. Their dedicated gateways provide better performance and reliability for production use. Access your content via:
- `https://gateway.pinata.cloud/ipfs/[CID]`

Learn more about the differences between public and dedicated gateways in [Pinata's gateway guide](https://knowledge.pinata.cloud/en/articles/6297294-public-gateways-vs-dedicated-gateways).

### Filebase Gateway
Filebase provides gateway access with the format:
- `https://[BUCKET_NAME].ipfs.filebase.io/ipfs/[CID]`

Note that Filebase's gateway may refuse HTML hosting and primarily works with assets like images or videos. For details, see [Filebase's IPFS gateway documentation](https://docs.filebase.com/ipfs-concepts/what-is-an-ipfs-gateway).

Check failure on line 96 in docs/quickstart/publish.md

View workflow job for this annotation

GitHub Actions / pr-content-check

[vale] reported by reviewdog 🐶 [docs.PLNSpelling] Did you really mean 'Filebase's'? Raw Output: {"message": "[docs.PLNSpelling] Did you really mean 'Filebase's'?", "location": {"path": "docs/quickstart/publish.md", "range": {"start": {"line": 96, "column": 127}}}, "severity": "ERROR"}

Check failure on line 96 in docs/quickstart/publish.md

View workflow job for this annotation

GitHub Actions / pr-content-check

[vale] reported by reviewdog 🐶 [docs.PLNSpelling] Did you really mean 'Filebase's'? Raw Output: {"message": "[docs.PLNSpelling] Did you really mean 'Filebase's'?", "location": {"path": "docs/quickstart/publish.md", "range": {"start": {"line": 96, "column": 11}}}, "severity": "ERROR"}

Check failure on line 96 in docs/quickstart/publish.md

View workflow job for this annotation

GitHub Actions / pr-content-check

[vale] reported by reviewdog 🐶 [docs.PLNSpelling] Did you really mean 'Filebase's'? Raw Output: {"message": "[docs.PLNSpelling] Did you really mean 'Filebase's'?", "location": {"path": "docs/quickstart/publish.md", "range": {"start": {"line": 96, "column": 127}}}, "severity": "ERROR"}

Check failure on line 96 in docs/quickstart/publish.md

View workflow job for this annotation

GitHub Actions / pr-content-check

[vale] reported by reviewdog 🐶 [docs.PLNSpelling] Did you really mean 'Filebase's'? Raw Output: {"message": "[docs.PLNSpelling] Did you really mean 'Filebase's'?", "location": {"path": "docs/quickstart/publish.md", "range": {"start": {"line": 96, "column": 11}}}, "severity": "ERROR"}

### Storacha Gateway
Storacha provides gateway access through w3s.link. You can retrieve content using formats like:
- `https://[CID].ipfs.w3s.link`
- `https://w3s.link/ipfs/[CID]`

For more details about their gateway options, see [Storacha's IPFS gateway documentation](https://docs.storacha.network/concepts/ipfs-gateways/).

Check failure on line 103 in docs/quickstart/publish.md

View workflow job for this annotation

GitHub Actions / pr-content-check

[vale] reported by reviewdog 🐶 [docs.PLNSpelling] Did you really mean 'Storacha's'? Raw Output: {"message": "[docs.PLNSpelling] Did you really mean 'Storacha's'?", "location": {"path": "docs/quickstart/publish.md", "range": {"start": {"line": 103, "column": 52}}}, "severity": "ERROR"}

Check failure on line 103 in docs/quickstart/publish.md

View workflow job for this annotation

GitHub Actions / pr-content-check

[vale] reported by reviewdog 🐶 [docs.PLNSpelling] Did you really mean 'Storacha's'? Raw Output: {"message": "[docs.PLNSpelling] Did you really mean 'Storacha's'?", "location": {"path": "docs/quickstart/publish.md", "range": {"start": {"line": 103, "column": 52}}}, "severity": "ERROR"}

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, from which you can retrieve the uploaded CID.
### Public Gateways
You can also use public IPFS gateways to retrieve any CID:
- `https://ipfs.io/ipfs/[CID]`
- `https://dweb.link/ipfs/[CID]`

To retrieve the CID, open the following URL:
[bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4.ipfs.w3s.link](https://bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4.ipfs.w3s.link/)
Simply replace `[CID]` with your actual CID in your browser's address bar to retrieve your file.

:::callout
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.
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. Many pinning services wrap files in a directory by default.
:::

## Summary and next steps

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/).
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 through web interfaces. You explored different pinning service options and learned how to retrieve your content through IPFS gateways.

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.

Possible next steps include:

- 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.
- Try fetching the pinned file by following the [retrieval quickstart](./retrieve.md).
- If you prefer to upload a file programmatically with JavaScript or Go, check out the [Web3.storage docs](https://web3.storage/docs/how-tos/store/).
- 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.
- 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
- Try fetching the pinned file by following the [retrieval quickstart](./retrieve.md)
- Learn how to [pin files using the command line](./publish_cli.md)
- Explore service-specific documentation:
- [Pinata documentation](https://docs.pinata.cloud/)
- [Filebase documentation](https://docs.filebase.com/)
- [Storacha documentation](https://docs.storacha.network)
Loading
Loading