diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt index 6246e9c4a..ea50f0b0c 100644 --- a/.github/styles/pln-ignore.txt +++ b/.github/styles/pln-ignore.txt @@ -12,9 +12,11 @@ arbol('s) arg auditable audius +astro auspinner bit[ss]wap bitswap +blockchain blockchains blockstore bool @@ -32,6 +34,7 @@ certbot cid cids cli +clis cmds cnames codec @@ -136,6 +139,7 @@ merkle merkleize merklizing merkleizing +merkleizes merkleized merkleization metadata('s) @@ -219,6 +223,7 @@ sneakernets stackparse stdout storj +storacha Someguy subcommand substring @@ -245,6 +250,7 @@ userspace vpns vscode vue +Vuepress wantlist wantlists web diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 5f713c8b0..f968aeb07 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -116,8 +116,8 @@ "MD025": { // Heading level "level": 1, - // RegExp for matching title in front matter - "front_matter_title": "^\\s*title\\s*[:=]" + // ignore the title in the front matter + "front_matter_title": "" }, // MD026/no-trailing-punctuation - Trailing punctuation in heading @@ -228,16 +228,6 @@ // Seems like a good rule to have in place "MD042": true, - // MD043/required-headings/required-headers - Required heading structure - // TODO - // We may want to utilize this rule, not sure what the struct would be - "MD043": { - // List of headings - "headings": [], - // List of headings - "headers": [] - }, - // MD044/proper-names - Proper names should have the correct capitalization // TODO // Determine if we want to use this, diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index a9b3e64f0..6dd290bb4 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -105,9 +105,8 @@ module.exports = { sidebarDepth: 1, collapsable: false, children: [ - ['/quickstart/publish','Publish with IPFS (UI)'], - ['/quickstart/publish_cli', 'Publish with IPFS (command line)' ], ['/quickstart/retrieve','Retrieve with IPFS'], + ['/how-to/websites-on-ipfs/deploy-github-action', 'Deploy to IPFS with GitHub Actions' ], ] }, { @@ -124,9 +123,8 @@ module.exports = { sidebarDepth: 1, collapsable: false, children: [ - ['/quickstart/publish','Publish with IPFS (UI)'], - ['/quickstart/publish_cli', 'Publish with IPFS (command line)' ], ['/quickstart/retrieve','Retrieve with IPFS'], + ['/how-to/websites-on-ipfs/deploy-github-action', 'Deploy to IPFS with GitHub Actions' ], ] }, @@ -243,10 +241,10 @@ module.exports = { sidebarDepth: 1, collapsable: true, children: [ + '/how-to/websites-on-ipfs/deploy-github-action', + '/how-to/websites-on-ipfs/custom-domains', '/how-to/websites-on-ipfs/single-page-website', '/how-to/websites-on-ipfs/multipage-website', - '/how-to/websites-on-ipfs/link-a-domain', - '/how-to/websites-on-ipfs/introducing-fleek', '/how-to/websites-on-ipfs/static-site-generators', '/how-to/websites-on-ipfs/redirects-and-custom-404s' ] diff --git a/docs/.vuepress/redirects b/docs/.vuepress/redirects index 9747f8956..e31980549 100644 --- a/docs/.vuepress/redirects +++ b/docs/.vuepress/redirects @@ -44,6 +44,7 @@ /how-to/troubleshoot-file-transfers /how-to/troubleshooting /how-to/run-ipfs-inside-docker /install/run-ipfs-inside-docker /how-to/ipfs-updater /install/command-line +/how-to/websites-on-ipfs/link-a-domain /how-to/websites-on-ipfs/custom-domains /install/command-line-quick-start/ /how-to/command-line-quick-start /install/js-ipfs/ https://github.com/ipfs/helia/wiki /introduction/ /concepts diff --git a/docs/README.md b/docs/README.md index 22f848e84..c655a2aa0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,33 +3,32 @@ title: IPFS Documentation description: The home page for developer documentation for IPFS, the InterPlanetary File System. --- -# Welcome to the IPFS docs +# Welcome to the IPFS Docs -The InterPlanetary File System (IPFS) is a set of composable, peer-to-peer protocols for addressing, routing, and transferring [content-addressed](concepts/glossary.md#content-addressing) data in a decentralized file system. Many popular Web3 projects are built on IPFS - see the [ecosystem directory](https://ecosystem.ipfs.tech) for a list of some of these projects. +IPFS is a set of building blocks for a better web. Open protocols to make your data smarter: content-addressed, verifiable, and unstoppable. -## Get started +On a more technical level, IPFS is a set of open protocols for addressing, routing, and transferring data on the web, built on the ideas of [content addressing](concepts/glossary.md#content-addressing) and peer-to-peer networking. -You can quickly [store and retrieve data](#store-and-retrieve-data) and [interact with the network via a simple GUI app or a standard browser](#interact-with-the-network). If you'd rather develop applications, learn how to build IPFS-native apps or use standard HTTP in the [Build](#build) section. +Many popular projects are built with IPFS - see the [ecosystem directory](https://ecosystem.ipfs.tech) and the [awesome-ipfs](https://github.com/ipfs/awesome-ipfs) list to find some of these projects. -:::callout -New to IPFS? Start with -[the 3-page Basic Concepts](./concepts/README.md#learn-the-basics). -::: +## Get started + +You can get started [retrieving data](#retrieve-data) and [providing data](#provide-data) to the IPFS network. If you'd rather develop applications, learn how to build IPFS-native apps or use standard HTTP in the [Build](#build) section. -### Store and retrieve data +### Retrieve data -Quickly store data and retrieve data, no complex applications or programming required: +Quickly retrieve data from the IPFS network, no programming required: -- Publish content to the IPFS network with a pinning service by following this [quickstart guide](./quickstart/publish.md). -- Fetch data via it's content identifier (CID) [using an IPFS gateway](./quickstart/retrieve.md#fetching-the-cid-with-an-ipfs-gateway). -- For long-term storage, use [Filecoin](https://docs.filecoin.io/), the peer-to-peer network with built-in economic incentives that stores data on IPFS. +- Fetch data via it's [content identifier (CID)](concepts/glossary.md#cid)[using an IPFS gateway](./quickstart/retrieve.md). +- Install the [IPFS Companion](./install/ipfs-companion.md) browser extension to add support for `ipfs://` and `ipns://` addresses to your browser. -### Interact with the network +### Provide data -You can quickly interact the IPFS network using a simple GUI or a standard browser: +Provide data to the IPFS network with IPFS Desktop or a pinning service: -- For a simple, easy-to-use GUI application that bundles an IPFS node, file manager, peer manager, and content explorer, use [IPFS Desktop](./install/ipfs-desktop.md). -- Interact with the network using any Brave, Chrome, Edge, Firefox, Opera, and any other Chromium-based web browser using the [IPFS Companion browser extension](./install/ipfs-companion.md). +- [Install IPFS Desktop which bundles an IPFS node (Kubo) and a UI to manage files, peers, and explore content on IPFS](./install/ipfs-desktop.md). +- [Publish content to the IPFS network with IPFS Desktop](./how-to/desktop-app.md). +- [Deploy static sites to the IPFS network with a GitHub Action](./how-to/websites-on-ipfs/deploy-github-action.md). ### Build @@ -37,15 +36,15 @@ You can build apps that leverage IPFS implementations, or use HTTP instead: #### Using IPFS -Build an IPFS-native app using one of the many IPFS implementations and tools built by and for Web3 users: +Build an IPFS-native app using one of the many IPFS [implementations](./concepts/ipfs-implementations.md) and tools: -- To develop IPFS applications using Go and/or interact with IPFS from the terminal, use the [IPFS Kubo implementation in Go](./install/command-line.md). -- If you'd rather use JavaScript, try the [IPFS Helia implementation in JavaScript](https://github.com/ipfs/helia). +- If you are familiar with JavaScript, checkout the [IPFS in web apps guide](./how-to/ipfs-in-web-apps.md), which covers how to use [Helia](https://github.com/ipfs/helia) and related libraries to build IPFS-native apps. +- To develop IPFS applications using Go and/or interact with IPFS from the terminal, use the [IPFS Kubo implementation](./install/command-line.md). - Try any of the [many other tools and implementations](./concepts/ipfs-implementations.md), which are written in different languages and tailored to specific needs and use cases. #### Using HTTP -Connect your Web2 application to the IPFS network using standard HTTP: +As the IPFS ecosystem has grown and evolved with multiple implementations in different languages, HTTP has become an important foundation for interoperability. Check out the following resources to learn more: - Control an IPFS Kubo node via HTTP using the [Kubo RPC API](./reference/kubo/rpc.md), which supports [multiple clients in multiple languages](./reference/kubo-rpc-cli.md). - For an implementation and runtime agnostic HTTP interface for retrieving data, use an [IPFS gateway](./reference/http/gateway.md). diff --git a/docs/concepts/dnslink.md b/docs/concepts/dnslink.md index 1113ea148..b0de1f66b 100644 --- a/docs/concepts/dnslink.md +++ b/docs/concepts/dnslink.md @@ -29,7 +29,7 @@ For example, [`docs.ipfs.tech`](https://docs.ipfs.tech) loads because a `TXT` re ```shell dig +noall +answer TXT _dnslink.docs.ipfs.tech -> _dnslink.docs.ipfs.tech. 30 IN TXT "dnslink=/ipfs/bafybeieenxnjdjm7vbr5zdwemaun4sw4iy7h4imlvvl433q6gzjg6awdpq" +> _dnslink.docs.ipfs.tech. 30 IN TXT "dnslink=/ipfs/bafybeifld3uybj6azujisdnxu6cm7mombldpbt3au4g33nwnqx7dsgjrta" ``` @@ -47,7 +47,7 @@ For example, let's go back to when we looked up the DNS records for `_dnslink.do ```sh $ dig +noall +answer TXT _dnslink.docs.ipfs.tech -_dnslink.docs.ipfs.tech. 34 IN TXT "dnslink=/ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya" +_dnslink.docs.ipfs.tech. 34 IN TXT "dnslink=/ipfs/bafybeifld3uybj6azujisdnxu6cm7mombldpbt3au4g33nwnqx7dsgjrta" ``` Based on that, this address: @@ -59,9 +59,12 @@ Based on that, this address: Will get you this block: ``` -/ipfs/QmVMxjouRQCA2QykL5Rc77DvjfaX6m8NL6RyHXRTaZ9iya/introduction/ +/ipfs/bafybeifld3uybj6azujisdnxu6cm7mombldpbt3au4g33nwnqx7dsgjrta/introduction/ ``` ## Further Resources +For more information on how to use DNSLink for your website or app, check out the [Custom domains and DNSLink](../how-to/websites-on-ipfs/custom-domains.md) guide. + For a complete guide to DNSLink β€” including tutorials, usage examples, and FAQs β€” check out [dnslink.dev](https://dnslink.dev/). + diff --git a/docs/concepts/faq.md b/docs/concepts/faq.md index 5c0b1ec10..602e4020d 100644 --- a/docs/concepts/faq.md +++ b/docs/concepts/faq.md @@ -7,7 +7,9 @@ description: Explore frequently asked questions about IPFS, the InterPlanetary F ## What is IPFS? -The InterPlanetary File System (IPFS) is a set of composable, peer-to-peer protocols for addressing, routing, and transferring [content-addressed](../concepts/glossary.md#content-addressing) data in a decentralized file system. Many popular Web3 projects are built on IPFS - see the [ecosystem directory](https://ecosystem.ipfs.tech) for a list of some of these projects. +IPFS is a set of building blocks for a better web. Open protocols to make your data smarter: content-addressed, verifiable, and unstoppable. + +On a more technical level, IPFS is a set of open protocols for addressing, routing, and transferring data on the web, built on the ideas of [content addressing](../concepts/glossary.md#content-addressing) and peer-to-peer networking. New to IPFS? Start with [the 3-page Basic Concepts](../concepts/README.md#learn-the-basics). @@ -86,4 +88,4 @@ IPFS is an open-source project with a community of more than four thousand contr ## Don't see your question? -We're working on expanding this FAQ with more content, including questions from the original-generation [IPFS forums](https://discuss.ipfs.tech/c/help/old-faq/5), so please watch this space! However, if you don't see your question, please [ask in the forums](https://discuss.ipfs.tech/), so you can get the answers you need and make us aware of new FAQ items. +If you don't see your question, please [ask in the IPFS forums](https://discuss.ipfs.tech/). diff --git a/docs/concepts/what-is-ipfs.md b/docs/concepts/what-is-ipfs.md index 75014a484..3e32bd6bd 100644 --- a/docs/concepts/what-is-ipfs.md +++ b/docs/concepts/what-is-ipfs.md @@ -5,8 +5,10 @@ description: Learn what IPFS is and isn't. # What is IPFS -IPFS is a modular suite of protocols for organizing and transferring data, designed from the ground up with the principles of content addressing and peer-to-peer networking. Because IPFS is open-source, there are multiple implementations of IPFS. -While IPFS has more than one use case, its main use case is for publishing data (files, directories, websites, etc.) in a decentralised fashion. +IPFS is a set of building blocks for a better web. Open protocols to make your data smarter: content-addressed, verifiable, and unstoppable. + +On a more technical level, IPFS is a set of open protocols for addressing, routing, and transferring data on the web, built on the ideas of [content addressing](../concepts/glossary.md#content-addressing) and peer-to-peer networking. + :::callout This guide is part 1 of a 3-part introduction to [the basic concepts of IPFS](../concepts/README.md#learn-the-basics). The second part, [**IPFS and the problems it solves**](../concepts/ipfs-solves.md), covers the problems with the internet and current protocols like HTTP that IPFS solves. diff --git a/docs/how-to/websites-on-ipfs/custom-domains.md b/docs/how-to/websites-on-ipfs/custom-domains.md new file mode 100644 index 000000000..da61cc493 --- /dev/null +++ b/docs/how-to/websites-on-ipfs/custom-domains.md @@ -0,0 +1,46 @@ +--- +title: Custom domains and DNSLink +description: Guide on how to use custom domains and DNSLink with IPFS deployed websites, allowing users to access your website or app via a custom domain. +--- + +# Custom domains and DNSLink + +By default, when you deploy a static web application to IPFS, it will be addressed with a CID. But CIDs are long, hard to remember, and not very user-friendly. For example, + + - `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.inbrowser.link/` or + - `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.dweb.link/`. + - `ipfs://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y` (if you have the [IPFS Companion](https://github.com/ipfs/ipfs-companion) browser extension installed) + +To make your website or app easier to access, you can link a custom domain for your website or web app using two approaches that can be used in combination: + +- [CID signaling with DNSLink](#cid-signaling-with-dnslink): allowing users to access your website from IPFS Gateways using the custom domain, e.g. `https://ipfs.io/ipns/docs.ipfs.tech` (note that it will redirect to a subdomain gateway `https://docs-ipfs-tech.ipns.dweb.link/` to ensure origin isolation). With this approach, you can access your website from a local IPFS Gateway or the Service Worker Gateway, benefiting from local verification and all the other benefits of IPFS like peer-to-peer retrieval and censorship resistance. +- [Access via a custom domain](#access-via-a-custom-domain) - Access your website via a custom domain name, e.g. `https://docs.ipfs.tech`. This is the common way for static websites to be deployed. Note that this approach does not benefit from the benefits of IPFS like peer-to-peer retrieval and censorship resistance if done without configuring DNSLink. + +The main difference between the two options is that CID signaling with DNSLink is mainly concerned with resolving a memorable domain name to a CID, while access via a custom domain is mainly concerned with accessing your website via a custom domain name. For most use cases, you probably want to use both approaches together or at the very least, use DNSLink to signal the CID for your website. + +This guide will walk you through the nuances of each of these options, and how to configure them for your app. + +### CID Signaling with DNSLink + +[DNSLink](../../concepts/dnslink.md) is a standard way to map human-readable domain names (DNS) to CIDs. For example, for the IPFS Docs, `docs.ipfs.tech`, the DNSLink record is a TXT record at `_dnslink.docs.ipfs.tech` with the value `dnslink=/ipfs/bafybeicv5tbyeahgm4pyskd2nverwsqxpiqloikqrufvof7vausglw6avm` (the CID will likely be different once you read this guide). + +The main benefit of DNSLink is that it allows users to determine the latest CID for a given domain name, while leaving it up to the user how to retrieve the deployment addressed by the CID. For example, a user might have a local IPFS node, and want to access the latest deployment of your app, they can do so by resolving the DNSLink record and fetching the content from their local node. `http://localhost:8080/ipns/docs.ipfs.tech` will serve the CID found in the DNSLink record. + +When a DNSLink record is present, any IPFS gateway (local or public) can take the DNS name and resolve it to the CID, and serve the content, for example, both `https://inbrowser.link/ipns/docs.ipfs.tech` and `https://dweb.link/ipns/docs.ipfs.tech` will serve the same site, albeit with different origins. + +If you run your own IPFS node, such as [IPFS Desktop](../../install/ipfs-desktop.md) or [Kubo](../../install/command-line.md), and load the site from a local gateway at `http://localhost:8080/ipns/docs.ipfs.tech`, you benefit from the resilience and censorship resistance of the IPFS network, because it's content addressed (addressed by CID) rather than being tied to a canonical origin. As long as there's at least one reachable provider for the CID, and use a trusted [DNS over HTTPS resolver](https://github.com/ipfs/kubo/blob/master/docs/config.md#dnsresolvers), you can access the site. + +Loading the site this way ties the website's cookies, storage, and Web API permissions to the [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) of a specific gateway. When using public gateways, the user experience can vary depending on the gateway's origin, which may impact app functionality, including cookies, storage, and CORS access to external APIs. That is why a local gateway is advantageous, as it does not depend on external domains or origins. + +## Access via a custom domain + +In the previous section, we discussed how DNSLink can be used to signal the CID for a domain name, while leaving it up to the user how to retrieve the content, be it a local node, service worker gateway or any other [public recursive gateway](https://docs.ipfs.tech/concepts/ipfs-gateway/#recursive-vs-non-recursive-gateways). + +With this approach, users can access your website via a custom domain name, e.g. `https://docs.ipfs.tech` but you can't easily verify the content, or load the site from a local node. Hence, it is recommended to use this as a complement to CID signaling with DNSLink. + +To provide access to the app directly via the custom domain, you have the following options: + +1. Self-host both the IPFS provider (e.g. [Kubo](https://github.com/ipfs/kubo)) and the HTTP gateway (e.g. [Kubo](https://github.com/ipfs/kubo) or [Rainbow](https://github.com/ipfs/rainbow/)). Deploy an IPFS Gateway that supports DNSLink resolution and point the `CNAME`/`A` DNS record for your custom domain to it and update the `TXT` record on `_dnslink` subdomain to match CID of your website. Set up CI automation to update TXT record every time your CID changes. You will likely want to also configure TLS with a reverse proxy like Caddy or use a CDN like Cloudflare for TLS termination. +2. Use a service like Fleek which encompasses both DNSLink and traditional web hosting (HTTP + TLS + CDN + [automatic DNSLink management](https://fleek.xyz/docs/platform/domains/#dnslink)). +3. Deploy the site to a web hosting service like [Cloudflare Pages](https://pages.cloudflare.com/) or [GitHub Pages](https://pages.github.com/) with a custom domain (pointing and configuring the `CNAME`/`A` record for your custom domain on the web hosting service), while managing the DNSLink `TXT` record on `_dnslink` subdomain separately, essentially getting the benefits of both IPFS and traditional web hosting. Remember to set up CI automation to update the DNSLink `TXT` record for every deployment that changes the CID. + diff --git a/docs/how-to/websites-on-ipfs/deploy-github-action.md b/docs/how-to/websites-on-ipfs/deploy-github-action.md new file mode 100644 index 000000000..0344856fb --- /dev/null +++ b/docs/how-to/websites-on-ipfs/deploy-github-action.md @@ -0,0 +1,304 @@ +--- +title: Deploy Static Apps to IPFS with GitHub Actions +description: Guide on how to setup GitHub Actions to deploy static sites/apps to IPFS using the IPFS Deploy Action. +current-ipfs-version: v0.34.0 +current-ipfs-cluster-version: v1.1.2 +--- + +# Deploy Static Apps to IPFS with GitHub Actions + +This guide will walk you through the process of configuring a [GitHub Actions](https://docs.github.com/en/actions) workflow to deploy a repository containing a static site or app to IPFS using the [IPFS Deploy Action](https://github.com/ipfs/ipfs-deploy-action). + +By the end of this guide, your web app (or just a static website) will be deployed to IPFS automatically when you push to your repository. It will also deploy pull request previews for each commit, and provide some other developer experience features, like commit status updates with the CID of the build, and a comment on pull requests with the IPFS CID and preview links. + +![IPFS Deploy Action](./images/github-action/commit-status.png) + +![IPFS Deploy Action](./images/github-action/pr-comment.png) + +Once deployed, each deployment of your app will be addressed by a CID and accessible via [recursive gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#recursive-vs-non-recursive-gateways), as well as the [Service Worker Gateway](https://inbrowser.link). + +To see what this looks like in a real-world example, check out the [IPNS Inspector](https://github.com/ipshipyard/ipns-inspector). + +## What is the IPFS Deploy Action? + +The [IPFS Deploy Action](https://github.com/ipfs/ipfs-deploy-action) is a [composite action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action), that can be called as a step in a [GitHub Actions workflow](https://docs.github.com/en/actions/writing-workflows), and combines the following features: + +- πŸ“¦ Merkleizes your static site into a [CAR](../../concepts/glossary.md#car) file +- πŸš€ Uploads CAR file to either [Storacha](https://storacha.network/), [IPFS Cluster](https://ipfscluster.io/), or [Kubo](https://github.com/ipfs/kubo#readme) +- πŸ“ Optional CID pinning to [Pinata](https://pinata.cloud/) +- πŸ’Ύ Optional CAR file upload to [Filebase](https://filebase.com/) +- πŸ’¬ PR Previews, with a comment containing the CID and preview links +- βœ… Commit Status updates + +The IPFS Deploy Action works with both self-hosted IPFS nodes (Kubo or IPFS Cluster) and pinning services (Storacha, Pinata, Filebase) and was built based on the best practices in 2025. + +The IPFS Deploy Action makes no assumptions about your build process. Whether you're using React, Vuepress, Astro, Next.js, or any other static site generator, this guide will help you get your web application deployed on IPFS. The only requirement is that your web application is static, meaning that once built, it is a folder containing HTML, CSS, and JavaScript files that are served as-is to the client. + +Note the IPFS Deploy Action is built on top of the following CLIs: + +- [Kubo CLI](https://github.com/ipfs/kubo#readme) for merkleizing builds with UnixFS, uploading CAR files to Kubo, and interacting with Pinning APIs +- [IPFS Cluster CTL](https://ipfscluster.io/documentation/reference/ctl/) for IPFS Cluster uploads +- [w3cli](https://docs.storacha.network/w3cli/) for Storacha uploads +- [AWS S3 CLI](https://aws.amazon.com/s3/) for Filebase CAR uploads + +## Prerequisites + +Before you begin, make sure you have: + +1. A GitHub repository with your static web application, this can be a single page application, or multi-page application (like Next.js) that requires no special server-side rendering or backend logic. +2. A [Storacha](https://storacha.network) account or an IPFS Node ([Kubo](https://github.com/ipfs/kubo#readme) or [IPFS Cluster](https://ipfscluster.io/)) with the [Kubo RPC](../../reference/kubo/rpc.md) endpoint publicly reachable (see [this guide](../kubo-rpc-tls-auth.md) for instructions on how to secure the Kubo RPC endpoint with TLS and authentication) + +This guide will use Storacha for simplicity. If you have an IPFS Node, you can skip the Storacha setup and use your own node instead. + +## Step 1: Setting Up Storacha + +If you don't have a Storacha account, you can create one at [storacha.network](https://storacha.network). + +1. Install the [`w3cli`](https://www.npmjs.com/package/@web3-storage/w3cli) tool: + + ```bash + npm install -g @web3-storage/w3cli + ``` + +2. Login to your Storacha account: + + ```bash + w3 login + ``` + +3. Create a new space for your deployments: + + ```bash + w3 space create my-app-space + ``` + +4. Create a signing key: + + ```bash + $ w3 key create --json + { + "did": "did:key:YOUR_KEY_DID", + "key": "STORACHA_KEY" + } + ``` + + Save the key value as a GitHub secret named `STORACHA_KEY` + +5. Create a [UCAN](https://docs.storacha.network/concepts/ucans-and-storacha/) proof. Note that the command will create a UCAN proof allowing uploads to the space created in step 3: + + ```bash + w3 delegation create did:key:YOUR_KEY_DID -c space/blob/add -c space/index/add -c filecoin/offer -c upload/add --base64 + ``` + + Save the output as a GitHub secret named `STORACHA_PROOF` + +## Step 2: Configure Your Workflow + +Create a new file `.github/workflows/deploy.yml` in your repository: + +```yaml +name: Deploy to IPFS + +permissions: + contents: read + pull-requests: write + statuses: write + +on: + push: + branches: + - main + pull_request: + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 'lts/*' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Build project + run: npm run build + + - name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + id: deploy + with: + path-to-deploy: dist # Change this to your build output directory + storacha-key: ${{ secrets.STORACHA_KEY }} + storacha-proof: ${{ secrets.STORACHA_PROOF }} + github-token: ${{ github.token }} +``` + +A couple of things to note: + +- This workflow assumes that your build command is `npm run build`. If your build command is different, you can change the `run` command in the build step. +- The `path-to-deploy` input is set to `dist` by default. If your build output directory is different, you can change the `path-to-deploy` input. + +## Step 3: Optional Configurations + +### Uploading the CAR file to a Kubo Node + +To upload the CAR file to a Kubo node instead of or in addition to Storacha: + +1. Get your [Kubo RPC endpoint](https://github.com/ipfs/kubo/blob/master/docs/config.md#addressesapi) and [API token](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) +2. Add them as [GitHub secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) named `KUBO_API_URL` and `KUBO_API_AUTH` +3. Add these lines to your workflow: + +```yaml +- name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + with: + # ... other inputs ... + kubo-api-url: ${{ secrets.KUBO_API_URL }} + kubo-api-auth: ${{ secrets.KUBO_API_AUTH }} +``` + +You can also customize the Kubo version and [`ipfs add` parameters](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-add) used for merkleizing your content: + +```yaml +- name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + with: + # ... other inputs ... + kubo-version: 'v0.34.0' # Default, change if needed + ipfs-add-options: '--cid-version 1 --chunker size-1048576' # Default options +``` + +### Using IPFS Cluster + +To upload the CAR file to an IPFS Cluster: + +1. Get your [IPFS Cluster CTL](https://ipfscluster.io/documentation/reference/ctl/) endpoint, username, and password +2. Add them as GitHub secrets +3. Add these lines to your workflow: + +```yaml +- name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + with: + # ... other inputs ... + cluster-url: ${{ secrets.CLUSTER_URL }} + cluster-user: ${{ secrets.CLUSTER_USER }} + cluster-password: ${{ secrets.CLUSTER_PASSWORD }} +``` + +You can also configure additional IPFS Cluster options: + +```yaml +- name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + with: + # ... other inputs ... + cluster-retry-attempts: '5' # Override number of retry attempts + cluster-timeout-minutes: '15' # Override timeout in minutes per attempt + ipfs-cluster-ctl-version: 'v1.1.2' # Default version + cluster-pin-expire-in: '720h' # Optional: Set pin to expire after time period (e.g., 30 days) +``` + +### Pinning with Pinata + +This works by sending a request to the [Pinning API](https://docs.pinata.cloud/api-reference/pinning-service-api) with the CID of the deployment, and Pinata handles pinning in the background. + +To pin your content to Pinata: + +1. Get your [Pinata JWT token](https://docs.pinata.cloud/api-reference/pinning-service-api#authentication) from the Pinata dashboard +2. Add it as a GitHub secret named `PINATA_JWT` +3. Add these lines to your workflow: + +```yaml +- name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + with: + # ... other inputs ... + pinata-jwt-token: ${{ secrets.PINATA_JWT_TOKEN }} + pinata-pinning-url: 'https://api.pinata.cloud/psa' # Default URL +``` + +### Adding Filebase Storage + +Note that Filebase only supports static websites for paid accounts. +To store CAR files on Filebase: + +1. [Create a Filebase account](https://docs.filebase.com/archive/content-archive/ipfs-getting-started-guide#signing-up-for-filebase) and [bucket](https://docs.filebase.com/archive/content-archive/ipfs-getting-started-guide#how-to-create-an-ipfs-bucket) +2. Get your access and secret keys +3. Add them as GitHub secrets +4. Add these lines to your workflow: + +```yaml +- name: Deploy to IPFS + uses: ipfs/ipfs-deploy-action@v1 + with: + # ... other inputs ... + filebase-bucket: 'your-bucket-name' + filebase-access-key: ${{ secrets.FILEBASE_ACCESS_KEY }} + filebase-secret-key: ${{ secrets.FILEBASE_SECRET_KEY }} +``` + +## Accessing Your Deployed Site + +After successful deployment, you can find the CID for commits: + +1. In the GitHub Actions run output, which will contain the IPFS CID +2. In the PR comments (if deploying from a PR) +3. In the commit status checks + +For example, here's where you can find the CID for a given commit on GitHub: + +![IPFS Deploy Action](./images/github-action/commit-status.gif) + +You can load the app using the CID from the commit status, and it will be accessible through: + +- [Public Good Gateway](../../concepts/public-utilities.md#public-ipfs-gateways): `https://.ipfs.dweb.link` +- [Service Worker Gateway](https://inbrowser.link): `https://.ipfs.inbrowser.link` +- [Storacha Gateway](https://docs.storacha.network/concepts/ipfs-gateways/) (if using Storacha): `https://.ipfs.w3s.link`. + +### With IPFS Desktop or Kubo + +If you have IPFS Desktop or Kubo installed, you can load with the local gateway exposed by IPFS Desktop or Kubo. + +For example, here's the URL for a given CID: `http://bafybeicbpllqfrjfygcdwkz2q5prdtu4q7obmsqr2fkk5byn45rs24ypcu.ipfs.localhost:8080` + +This URL uses subdomain resolution (where the CID has its own subdomain), which ensures [origin isolation](../gateway-best-practices.md/#use-subdomain-gateway-resolution-for-origin-isolation) per CID. + +## Troubleshooting + +1. **Build Output Directory Not Found** + + - Double-check the `path-to-deploy` matches your build output directory + - Ensure your build command is completing successfully + +2. **Authentication Issues** + + - Verify your credentials are correctly set in GitHub secrets + - Check that the secrets are properly referenced in the workflow file + - For Storacha, ensure both the key and proof are provided + - For IPFS Cluster, ensure URL, username, and password are all provided + - For Kubo, ensure both API URL and auth are provided + +3. **Workflow Permission Issues** + - Ensure the `permissions` block is included in your workflow + - Check that your GitHub token has the necessary permissions + +## Best Practices + +1. Always use a specific version of the action (e.g., `@v1`) +3. Consider using multiple IPFS providers for redundancy +4. Use environment-specific configurations when needed + +## Getting Help + +If you encounter any issues: + +1. Check the GitHub Actions run logs for detailed error messages +2. Review the [action's README](https://github.com/ipfs/ipfs-deploy-action) for updates +3. Open an issue in the [action's repository](https://github.com/ipfs/ipfs-deploy-action/issues/new) with detailed information about your setup and the problem you're experiencing diff --git a/docs/how-to/websites-on-ipfs/images/github-action/commit-status.gif b/docs/how-to/websites-on-ipfs/images/github-action/commit-status.gif new file mode 100644 index 000000000..5eff85383 Binary files /dev/null and b/docs/how-to/websites-on-ipfs/images/github-action/commit-status.gif differ diff --git a/docs/how-to/websites-on-ipfs/images/github-action/commit-status.png b/docs/how-to/websites-on-ipfs/images/github-action/commit-status.png new file mode 100644 index 000000000..20ae196c8 Binary files /dev/null and b/docs/how-to/websites-on-ipfs/images/github-action/commit-status.png differ diff --git a/docs/how-to/websites-on-ipfs/images/github-action/pr-comment.png b/docs/how-to/websites-on-ipfs/images/github-action/pr-comment.png new file mode 100644 index 000000000..f4f19edae Binary files /dev/null and b/docs/how-to/websites-on-ipfs/images/github-action/pr-comment.png differ diff --git a/docs/how-to/websites-on-ipfs/images/single-page-website/random-planets-with-correct-url.png b/docs/how-to/websites-on-ipfs/images/single-page-website/random-planets-with-correct-url.png deleted file mode 100644 index 59bd0412e..000000000 Binary files a/docs/how-to/websites-on-ipfs/images/single-page-website/random-planets-with-correct-url.png and /dev/null differ diff --git a/docs/how-to/websites-on-ipfs/link-a-domain.md b/docs/how-to/websites-on-ipfs/link-a-domain.md deleted file mode 100644 index df4b7588b..000000000 --- a/docs/how-to/websites-on-ipfs/link-a-domain.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Link a domain -description: Allow users to access your IPFS hosted site by linking up a domain name. ---- - -# Link a domain - -Users can view your website by entering its content identifier (CID) into their address bar. But, much like IP addresses, CIDs aren't particularly user-friendly or nice to look at. To fix this, we can map a domain name to your CID, so when users visit `www.YourDomain.com` they'll be forwarded to your site hosted on IPFS. This guide shows you how to map a regular domain name through DNS, and decentralized domains through the Ethereum naming service (ENS) or Handshake. - -This section is completely optional, but following it will give you a solid grasp on how to manage domain names with IPFS. - -## Domain name service (DNS) - -See [dnslink.io](https://dnslink.io) for explanation and instructions. - -## Ethereum naming service (ENS) - -The Ethereum Name Service (ENS) is a decentralized way to address resources. Like DNS, which converts human-readable names to IP addresses, ENS converts human-readable names such as `randomplanetfacts.eth.link` to Ethereum addresses. These addresses can then be used to point to CIDs on IPFS. Without going into too much detail, ENS aims to fix some of DNS's problems, mainly man-in-the-middle attacks and scalability. For more information on why DNS is broken, [check out Cynthia Taylor's post on recompilermag.com](https://recompilermag.com/issues/issue-1/the-web-is-broken-how-dns-breaks-almost-every-design-principle-of-the-internet/). - -### Things you'll need - -You need these things to get a domain name through ENS: - -- The [Metamask](https://metamask.io/) browser extension installed. -- An Ethereum account with some `ETH` in it. -- A website hosted on IPFS. If you've been following this tutorial series, you should already have a website and CID ready. -- A cool idea for a domain name! - -:::tip The price of domain names -The cost of your domain depends on a few things: - -- Which domain you want to purchase. -- The current price of ETH. -- The gas fees associated with your transaction. -- How long you want the domain for. - -The more years you choose to prepay, the less you will spend on gas fees overall: `(1 year + 1 gas fee) < (10 years + 1 gas fee) < (10 * (1 year + 1 gas fee))` -::: - -### Purchase an Ethereum domain name - -1. Go to `ens.eth` using a browser that supports ENS domains, like Brave or Opera. You can also go to [app.ens.domains](https://app.ens.domains/) to use regular DNS and the centralized web. -2. Log in to MetaMask: - - ![Metamask pop-up showing a login screen.](./images/link-a-domain/ens-metamask-log-into-key.png) - -3. Search for the domain you want to use: - - ![Searching for a domain in ENS.](./images/link-a-domain/ens-search-for-domain-name.png) - -4. Click on the domain if it's available. -5. Click **Request To Register**: - - ![Registration screen within ENS.](./images/link-a-domain/ens-request-to-register.png) - -6. In the MetaMask window that pops up, click **Confirm**. This action will cost you `ETH`. -7. Wait for the _Request to register_ transaction to complete. This process can take a couple of minutes: - - ![Registration screen within ENS.](./images/link-a-domain/ens-registration-transaction-pending.png) - -8. ENS requires that you wait for around a minute once the transaction has been completed. This delay is to make sure there is no-one else attempting to purchase the same domain at the same time as you: - - ![Waiting for registration confirmation screen in ENS.](./images/link-a-domain/ens-wait-a-minute.png) - -9. Click **Register**. Then click **Confirm** in the MetaMask window that pops up: - - ![2nd transaction confirmation within MetaMask.](./images/link-a-domain/ens-metamask-complete-registration-transaction.png) - -10. Wait for the transaction to be confirmed. This process can take a couple of minutes: - - ![Waiting for the 2nd transaction to be verified.](./images/link-a-domain/ens-complete-registration.png) - - You should now be able to see all the settings for your `.eth` domain: - - ![All the domain settings within ENS](./images/link-a-domain/ens-domain-settings-page.png) - -### Link your IPFS content identifier (CID) - -11. Click the plus `+` icon next to **Records**: - - ![The "add new records" icon in ENS.](./images/link-a-domain/ens-add-records-icon.png) - -12. Select **Content** from the dropdown: - - ![Records dropdown menu in ENS.](./images/link-a-domain/ens-add-content-record.png) - -13. Set the **Content** text box as the CID of your website, prefixed with `ipfs://`: - - ![Setting the content record as an IPFS CID.](./images/link-a-domain/ens-set-content-record-as-ipfs-cid.png) - -14. Confirm this change by clicking **Confirm** in the MetaMask pop-up: - - ![MetaMask confirmation pop-up for changing a content record.](./images/link-a-domain/ens-metamask-content-record-transaction.png) - - This transaction can take a couple of minutes to complete. - -In a few minutes, you'll be able to go to `Your_Domain.eth/` and view your website. Note the trailing slash `/`. Because `.eth` is not a registered DNS top-level domain, it is normally inaccessible through regular browsers. - -[Eth.link](https://eth.link/) provides a way for any browser to access your website. Just append `.link` to your domain. For example, `Your_Domain.eth.link`. There are no additional steps required for this. - -## Handshake - -Handshake is a blockchain built specifically for DNS. - -When you attempt to visit a website like GitHub.com, your browser will first need to figure out how to get to .com’s servers. To find .com, your browser will consult something called the root zone file β€” you can think of it like a spreadsheet where Column A are the top-level domains like .com, .net, .org, .io, and Column B are the servers each TLD points to. Controlling the root zone file is a single entity called ICANN, and they alone dictate whether you’re allowed to have a top-level domain. - -Handshake is shifting control of the root zone file away from ICANN to a decentralized blockchain. From a practical standpoint, Handshake provides fully decentralized and uncensorable top-level domains that you can own and use for your websites. To learn more, visit the [Namebase Learning Center](https://learn.namebase.io). - -### Prerequisites - -Before we get started, you will need: - -- A [Handshake domain](https://learn.namebase.io/starting-from-zero/how-to-get-a-name) -- The CID of your website hosted on IPFS -- A [way for resolving Handshake domains](https://www.namebase.io/blog/how-to-access-handshake-domains/) (to test the setup) - -### Bare TLD - -1. Access your name's DNS records. You're looking for where you can add `ALIAS` and `TXT` records for your domain. -1. Create an `ALIAS` record: - a. Set the **Host** to `@`. - a. Set the **Value** to `ipfs.namebase.io.` and notice the trailing dot `.` at the end of `ipfs.namebase.io.` -1. Create a `TXT` record: - a. Set the **Host** to `_dnslink`. - a. Set the value to `dnslink=/ipfs/SITE_CID`, replacing `SITE_CID` with the CID of your website. -1. Save your changes. - -You should now be able to visit your IPFS website at your Handshake domain! If your Handshake name is `yourname/`, you can visit your website at http://yourname/ - (no dots, just yourname/!) - -### Subdomain - -If you want to create your website on a subdomain rather than a bare TLD (e.g. `sub.yourname/` vs. `yourname/`), follow these instructions instead: - -1. Access your name's DNS records. You're looking for where you can add `CNAME` and `TXT` records for your domain. -1. Create a `CNAME` record: - a. Set the **Host** to `sub`, replacing `sub` with your desired subdomain name. - b. Set the **Value** to `ipfs.namebase.io.` and notice the trailing dot `.` at the end of `ipfs.namebase.io.` -1. Create a `TXT` record: - a. Set the **Host** to `_dnslink.sub`, replacing `sub` with your desired subdomain name. - b. Set the value to `dnslink=/ipfs/SITE_CID`, replacing `SITE_CID` with the CID of your website. -1. Save your changes. - -You should now be able to visit your IPFS website at your Handshake domain! If your Handshake name is `sub.yourname/`, you can visit your website at - http://sub.yourname/ - - -::: tip -If you prefer to use Handshake-powered DNSLink with your custom gateway, run [`ipfs daemon`](../../install/command-line.md) with config that has a Handshake resolver enabled for your domain: `ipfs config --json DNS.Resolvers '{ "yourname": "https://query.hdns.io/dns-query" }`. Learn how to run a self-hosted, site-specific DNSLink gateway from [gateway recipes in Kubo config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#gateway-recipes). -::: - -## Up next - -In the next tutorial in this series, we'll take a look at a tool that will help make this whole process easier: [Fleek](introducing-fleek.md). diff --git a/docs/how-to/websites-on-ipfs/multipage-website.md b/docs/how-to/websites-on-ipfs/multipage-website.md index 28f2e420b..617c9031f 100644 --- a/docs/how-to/websites-on-ipfs/multipage-website.md +++ b/docs/how-to/websites-on-ipfs/multipage-website.md @@ -16,7 +16,7 @@ If you followed the previous tutorial, you would already have the IPFS Desktop a Before we dig into IPFS, let's first create the files we'll need for this mini-project. 1. Create a folder called `multi-page-first-step`. -1. Within this new folder, create a file called `index.html` and paste in the following code. We'll continue using the [Random Planet Facts](http://randomplanetfacts.xyz) website from the previous tutorial, with an added link to an _About_ page: +2. Within this new folder, create a file called `index.html` and paste in the following code. We'll continue using the Random Planet Facts website from the previous tutorial, with an added link to an _About_ page: ```html @@ -236,7 +236,4 @@ Instead of sharing the CID of your website, you publish the root CID of your web This is just the tip of the iceberg when it comes to IPNS. [Check out the IPNS page to learn more β†’](../../concepts/ipns.md) -## Up next - -In the next tutorial, we'll look at [linking a domain name to your site!](../../how-to/websites-on-ipfs/link-a-domain.md) diff --git a/docs/how-to/websites-on-ipfs/single-page-website.md b/docs/how-to/websites-on-ipfs/single-page-website.md index d41ec2f0c..bae14a5da 100644 --- a/docs/how-to/websites-on-ipfs/single-page-website.md +++ b/docs/how-to/websites-on-ipfs/single-page-website.md @@ -1,9 +1,9 @@ --- -title: Host a single-page website on IPFS +title: Host a single-page website with IPFS Desktop description: Learn how to host a simple one-page website on IPFS and link up a domain name. --- -# Host a single-page website on IPFS +# Host a single-page website with IPFS Desktop In this tutorial, we will host a simple one-page website on IPFS and link up a domain name. This is the first step is a series of tutorials to teach web developers on how to build websites and applications using IPFS. @@ -250,8 +250,6 @@ We used Namecheap, but the process is very similar across all domain name servic Domain name services are fairly slow to update. You should be able to go to your domain and see the website you pinned in a few hours. -![Random planet facts site with the randomplanetfacts.xyz URL.](./images/single-page-website/random-planets-with-correct-url.png) - ## Up next This project was designed to get you up and running quickly, but there are many improvements we can make here. diff --git a/docs/how-to/websites-on-ipfs/static-site-generators.md b/docs/how-to/websites-on-ipfs/static-site-generators.md index a6633c9f9..ca2568170 100644 --- a/docs/how-to/websites-on-ipfs/static-site-generators.md +++ b/docs/how-to/websites-on-ipfs/static-site-generators.md @@ -1,11 +1,46 @@ --- title: Static-site generators -description: +description: A guide to configuring popular static-site generators (Next.js, Hugo, VuePress, Middleman, Jekyll) for optimal deployment to IPFS, including best practices and configuration tips --- # Static-site generators -Static-site generators like Hugo, Jekyll, Middleman, Next.js, and VuePress are all incredibly popular platforms building websites quickly. This guide walks through how to integrate IPFS into each of these workflows. +Static-site generators like Hugo, Jekyll, Middleman, Next.js, and VuePress are all popular platforms for building static sites quickly. This guide walks through how to configure each of these generators to build for deployment to IPFS. + +Check out the [IPFS Deploy GitHub Action Guide](./deploy-github-action.md) to automate the deployment of your static site to IPFS using GitHub Actions. + +## Next.js + +When deploying a Next.js site to IPFS, make sure that your site uses [Static Site Generation (SSG)](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation), so that it can be [built as a static site](https://nextjs.org/docs/pages/building-your-application/deploying/static-exports). + +1. First, ensure your `next.config.js` file has the following settings: + +```js +module.exports = { + output: 'export', // Enables static exports + trailingSlash: true // Required for IPFS gateway compatibility +} +``` + +Key points about the configuration: + +- `output: "export"` tells Next.js to generate a static site +- `trailingSlash: true` ensures routing works when the site is served from IPFS gateways (which require an index.html file per route) + +To build your Next.js site: + +```bash +npx next build +``` + +The static site will be generated in the `./out` directory. + +### Important Considerations + +- Only use [Static Site Generation (SSG)](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) features. +- Server-side features like `getServerSideProps` or API routes won't work. +- Dynamic routes need to be pre-rendered at build time. +- Use relative URLs for all internal links. ## Hugo @@ -27,7 +62,7 @@ Output will be in `./public/` directory by default. Upload the public folder to ## VuePress -Refer to VuePress' [Getting Started](https://vuepress.vuejs.org/guide/) to install and set up your project. +Refer to VuePress' [Getting Started](https://vuepress.vuejs.org/guide/getting-started.html) to install and set up your project. To build a static site: @@ -52,20 +87,20 @@ Refer the Middleman's [Installation](https://middlemanapp.com/basics/install/) g 1. Enable relative links and disable index file strip in your project's `config.rb` file: - ```ruby - set :relative_links, true - set :strip_index_file, false - ``` + ```ruby + set :relative_links, true + set :strip_index_file, false + ``` - Links generated by the `link_to` helper or by markdown will become relative. +Links generated by the `link_to` helper or by Markdown will become relative. 1. Build your static site: - ```bash - middleman build - ``` + ```bash + middleman build + ``` - Middleman will output your site to the `./build` folder. + Middleman will output your site to the `./build` folder. 1. Upload the `build` folder to IPFS. @@ -94,6 +129,9 @@ Upload the `_site` folder to IPFS. ## WordPress -While WordPress is not a static site generator, it is possible to turn it into a static website and migrate it over to a static-hosting service. [Take a look at this blog post from Fleek that walks you through the whole process](https://blog.fleek.co/posts/wordpress+fleek)! +While WordPress is not a static site generator, it is possible to turn it into a static website allowing deployment to IPFS. + +There are several plugins available to help you generate a static version of your WordPress site: -Keep in mind that you will lose the ability to manage your website's content through the WordPress _back-end_, and that this process requires that you install a plugin along-side your WordPress site. +- [WP2Static](https://github.com/elementor/wp2static) +- [Simply Static](https://wordpress.org/plugins/simply-static/) diff --git a/docs/quickstart/retrieve.md b/docs/quickstart/retrieve.md index f8c946af7..94a255d14 100644 --- a/docs/quickstart/retrieve.md +++ b/docs/quickstart/retrieve.md @@ -7,7 +7,7 @@ description: 'Learn about the different ways that CIDs can be fetched from the o In this quickstart guide, you will learn the different approaches to retrieving CIDs from the IPFS network and how to pick the most appropriate method for your specific needs. -You will fetch the image that was pinned in the [publishing with a pinning service quickstart guide](./publish.md) which has the following CID: `bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4`. +You will fetch the image with the following CID: `bafkreie7ohywtosou76tasm7j63yigtzxe7d5zqus4zu3j6oltvgtibeom`. :::callout The CID you will retrieve is actually a folder containing a single image file. The reason for this that when files are added to IPFS, the filename is not stored by default. To retain the filename, it's a common practice to wrap the file in a directory. In such instances, you end up with two CIDs - one for the file and another for the directory containing the file. @@ -74,13 +74,34 @@ To fetch the CID with [Kubo](../install/command-line.md), complete the steps bel Congratulations, you have successfully fetched the CID. +## Verified retrieval with Helia Verified Fetch + +[Verified Fetch](https://www.npmjs.com/package/@helia/verified-fetch) simplifies **verified** retrieval of CIDs on the web by abstracting away the details of content routing, transports and retrieval. The API is similar to the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), accepting CIDs instead of URLs, returning [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects. + +For example, the following code fetches the image using the `verifiedFetch` library: + + + + +:::callout +You may notice that there's a path following the CID, e.g. `bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4/welcome-to-IPFS.jpg`, because the starting CID is a directory containing the `welcome-to-IPFS.jpg` file, which you can fetch directly with: `verifiedFetch('ipfs://bafkreie7ohywtosou76tasm7j63yigtzxe7d5zqus4zu3j6oltvgtibeom')`. +::: + + ## Fetching the CID with an IPFS Gateway To fetch the CID using an IPFS gateway is as simple as loading one of the following URLs: - [https://ipfs.io/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://ipfs.io/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4) - [https://dweb.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://dweb.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4) -- [https://gateway.pinata.cloud/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://gateway.pinata.cloud/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4) +- [https://inbrowser.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4](https://inbrowser.link/ipfs/bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4) + + +> `inbrowser.link` is powered by the [Service Worker Gateway](https://github.com/ipfs/service-worker-gateway) which handles retrieval and verification in the browser, also leveraging in-browser caching, making subsequent loads faster, and local when you're offline. ## Summary and next steps