Skip to content

Commit 856ae50

Browse files
2color2color
committed
break off dnslink and custom domains into separate guide
1 parent 2230c2d commit 856ae50

File tree

3 files changed

+123
-73
lines changed

3 files changed

+123
-73
lines changed

‎docs/.vuepress/config.js‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,6 @@ module.exports = {
105105
sidebarDepth: 1,
106106
collapsable: false,
107107
children: [
108-
['/quickstart/publish','Publish with IPFS (UI)'],
109108
['/quickstart/publish_cli', 'Publish with IPFS (command line)' ],
110109
['/quickstart/retrieve','Retrieve with IPFS'],
111110
]

‎docs/how-to/websites-on-ipfs/custom-domains.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Custom domains and DNSLink
3+
description: Guide on how to configure custom domains and DNSLink for your IPFS deployments.
4+
---
5+
6+
# Custom domains and DNSLink
7+
8+
By default, when you deploy a static web application to IPFS, it will be addressed with a CID. Since CIDs are long and hard to remember, they're not very user-friendly, for example, `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.inbrowser.link/` or `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.dweb.link/`.
9+
10+
To make your app easier to access, you can optionally configure a custom domain for your app, depending on how you want users to access your app.
11+
12+
This guide will walk you through the process of configuring a custom domain for your app, and how to configure DNSLink to signal the CID for your app.
13+
14+
### CID Signaling with DNSLink
15+
16+
[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).
17+
18+
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.
19+
20+
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 `http://inbrowser.link/ipns/docs.ipfs.tech` and `http://ipfs.io/ipns/docs.ipfs.tech` will serve the same site, albeit with different origins.
21+
22+
When loading the site this way, 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, you can access the site.
23+
24+
The disadvantage is that loading the site this way is that the [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) can vary depending on where the user is accessing the site from, which can impact how your app functions, like CORS access to external APIs.
25+
26+
## Access via custom domain
27+
28+
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). In this instance, the user provides the domain name as input, instead of the CID.
29+
30+
To provide access to the app directly via the custom domain, you have the following options:
31+
32+
1. Deploy an IPFS Gateway that supports DNSLink, e.g. [Rainbow](https://github.com/ipfs/rainbow/) and point the CNAME/A record for your custom domain to it. You will likely want to also configure TLS with a reverse proxy like Caddy.
33+
2. Use a service like Fleek
34+
3. Deploy the site to a web hosting service like Cloudflare/GitHub Pages, and point the CNAME/A record for your custom domain to it, essentially getting the benefits of both IPFS and traditional web hosting.
35+
36+
Access via a custom domain is useful if you want to serve your app via a domain name that you own, for example, `app.example.com`.

‎docs/install/deploy-github-action.md‎

Lines changed: 87 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
---
2-
title: Deploying Static Web Applications to IPFS
3-
description: Guide on how to setup GitHub Actions to deploy static web applications to IPFS using the IPFS Deploy Action.
2+
title: Deploy Static Apps to IPFS with GitHub Actions
3+
description: Guide on how to setup GitHub Actions to deploy static sites/apps to IPFS using the IPFS Deploy Action.
44
---
55

6-
# Deploying Static Web Applications to IPFS with GitHub Actions
6+
# Deploy Static Apps to IPFS with GitHub Actions
77

8-
This guide will walk you through the process of configureing a GitHub Actions workflow to deploy a repository containing a static web application to IPFS using the [IPFS Deploy Action](https://github.com/ipfs/ipfs-deploy-action).
8+
This guide will walk you through the process of configureing a GitHub 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).
99

1010
By the end of this guide, your app 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.
1111

1212
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).
1313

14-
To see what this looks like in a real-world example, check out the [IPNS Inspector](https://github.com/ipfs-shipyard/ipfs-deploy-action-demo).
14+
To see what this looks like in a real-world example, check out the [IPNS Inspector](https://github.com/ipshipyard/ipns-inspector).
1515

1616
## What is the IPFS Deploy Action?
1717

@@ -28,52 +28,24 @@ The IPFS Deploy Action works with both self-hosted IPFS nodes (Kubo or IPFS Clus
2828

2929
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.
3030

31-
## Custom domains and DNSLink
32-
33-
**TODO: This whole section should probably move to a separate guide that can be linked to from here**
34-
35-
By default, each deployment will be addressed with a CID. Since CIDs are long and hard to remember, they're not very user friendly, for example, `https://bafybeifhgtpm6kmbyqszbardceszvkv5rsi3dodtuufpcfskzggekcfl2y.ipfs.inbrowser.link/`.
36-
37-
To make your deployments easier to access, you can optionally configure a custom domain for your app, depending on how you want users to access your app.
38-
39-
### CID Signaling with DNSLink
40-
41-
DNSLink 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).
42-
43-
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.
44-
45-
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 `http://inbrowser.link/ipns/docs.ipfs.tech` and `http://ipfs.io/ipns/docs.ipfs.tech` will serve the same site, albeit with different origins.
46-
47-
When loading the site this way, 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, you can access the site.
48-
49-
The disadvantage is that loading the site this way is that the [origin](https://developer.mozilla.org/en-US/docs/Glossary/Origin) can vary depending on where the user is accessing the site from, which can impact how your app functions, like CORS access to external APIs.
50-
51-
## Access via custom domain
52-
53-
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). In this instance, the user provides the domain name as input, instead of the CID.
54-
55-
To provide access to the app directly via the custom domain, you have the following options:
56-
57-
1. Deploy an IPFS Gateway that supports DNSLink, e.g. [Rainbow](https://github.com/ipfs/rainbow/) and point the CNAME/A record for your custom domain to it. You will likely want to also configure TLS with a reverse proxy like Caddy.
58-
2. Use a service like Fleek
59-
3. Deploy the site to a web hosting service like Cloudflare/GitHub Pages, and point the CNAME/A record for your custom domain to it, essentially getting the benefits of both IPFS and traditional web hosting.
60-
61-
Access via a custom domain is useful if you want to serve your app via a domain name that you own, for example, `app.example.com`.
62-
6331
## Prerequisites
6432

6533
Before you begin, make sure you have:
6634

6735
1. A GitHub repository with your static web application
68-
2. GitHub Actions enabled on your repository
69-
3. A Storacha account or running your own IPFS Node (Kubo or IPFS Cluster)
36+
2. A [Storacha](https://storacha.network) account or an IPFS Node (Kubo or IPFS Cluster) with the RPC endpoint publicly reachable (see [this guide](../how-to/kubo-rpc-tls-auth.md) for instructions on how to secure the Kubo RPC endpoint with TLS and authentication)
37+
38+
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.
39+
40+
## Step 1: Setting Up Storacha
41+
42+
If you don't have a Storacha account, you can create one at [https://storacha.network](https://storacha.network).
7043

71-
## Step 1: Setting Up Storacha (Easiest way to get started)
7244

7345
1. Install the w3cli tool:
7446

7547
```bash
76-
npm install -g @storacha/w3cli
48+
npm install -g @web3-storage/w3cli
7749
```
7850

7951
2. Login to your Storacha account:
@@ -100,7 +72,8 @@ Before you begin, make sure you have:
10072

10173
Save the key value as a GitHub secret named `STORACHA_KEY`
10274

103-
5. Create a UCAN proof:
75+
5. Create a UCAN proof. Note that the command will create a UCAN proof allowing uploads to the space created in step 3:
76+
10477
```bash
10578
w3 delegation create did:key:YOUR_KEY_DID -c space/blob/add -c space/index/add -c filecoin/offer -c upload/add --base64
10679
```
@@ -153,21 +126,75 @@ jobs:
153126
github-token: ${{ github.token }}
154127
```
155128
156-
## Step 3: Customize Build Output Directory
129+
A couple of things to note:
157130
158-
Modify the `path-to-deploy` input based on your build tool:
131+
- 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.
132+
- 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.
159133

160-
- React (Create React App): `build`
161-
- Next.js: `out` (when using `next export`) or `.next` (for server-side rendering)
162-
- Vue.js: `dist`
163-
- Vite: `dist`
164-
- Gatsby: `public`
134+
## Step 3: Optional Configurations
165135

166-
## Step 4: Optional Configurations
136+
### Uploading the CAR file to a Kubo Node
167137

168-
### Adding Pinata Backup
138+
To upload the CAR file to a Kubo node instead of or in addition to Storacha:
169139

170-
To add redundancy with Pinata pinning:
140+
1. Get your Kubo RPC endpoint and API token
141+
2. Add them as GitHub secrets named `KUBO_API_URL` and `KUBO_API_AUTH`
142+
3. Add these lines to your workflow:
143+
144+
```yaml
145+
- name: Deploy to IPFS
146+
uses: ipfs/ipfs-deploy-action@v1
147+
with:
148+
# ... other inputs ...
149+
kubo-api-url: ${{ secrets.KUBO_API_URL }}
150+
kubo-api-auth: ${{ secrets.KUBO_API_AUTH }}
151+
```
152+
153+
You can also customize the Kubo version used for merkleizing your content:
154+
155+
```yaml
156+
- name: Deploy to IPFS
157+
uses: ipfs/ipfs-deploy-action@v1
158+
with:
159+
# ... other inputs ...
160+
kubo-version: 'v0.33.0' # Default, change if needed
161+
ipfs-add-options: '--cid-version 1 --chunker size-1048576' # Default options
162+
```
163+
164+
### Using IPFS Cluster
165+
166+
To upload the CAR file to an IPFS Cluster:
167+
168+
1. Get your IPFS Cluster URL, username, and password
169+
2. Add them as GitHub secrets
170+
3. Add these lines to your workflow:
171+
172+
```yaml
173+
- name: Deploy to IPFS
174+
uses: ipfs/ipfs-deploy-action@v1
175+
with:
176+
# ... other inputs ...
177+
cluster-url: ${{ secrets.CLUSTER_URL }}
178+
cluster-user: ${{ secrets.CLUSTER_USER }}
179+
cluster-password: ${{ secrets.CLUSTER_PASSWORD }}
180+
```
181+
182+
You can also configure additional IPFS Cluster options:
183+
184+
```yaml
185+
- name: Deploy to IPFS
186+
uses: ipfs/ipfs-deploy-action@v1
187+
with:
188+
# ... other inputs ...
189+
cluster-retry-attempts: '3' # Default number of retry attempts
190+
cluster-timeout-minutes: '5' # Default timeout in minutes per attempt
191+
ipfs-cluster-ctl-version: 'v1.1.2' # Default version
192+
cluster-pin-expire-in: '720h' # Optional: Set pin to expire after time period (e.g., 30 days)
193+
```
194+
195+
This works by sending a request to the Pinning API with the CID of the deployment, and Pinata handles pinning in the background.
196+
197+
To pin your content to Pinata:
171198

172199
1. Get your Pinata JWT token from the Pinata dashboard
173200
2. Add it as a GitHub secret named `PINATA_JWT`
@@ -178,7 +205,8 @@ To add redundancy with Pinata pinning:
178205
uses: ipfs/ipfs-deploy-action@v1
179206
with:
180207
# ... other inputs ...
181-
pinata-jwt-token: ${{ secrets.PINATA_JWT }}
208+
pinata-jwt-token: ${{ secrets.PINATA_JWT_TOKEN }}
209+
pinata-pinning-url: 'https://api.pinata.cloud/psa' # Default URL
182210
```
183211

184212
### Adding Filebase Storage
@@ -200,24 +228,6 @@ To store CAR files on Filebase:
200228
filebase-secret-key: ${{ secrets.FILEBASE_SECRET_KEY }}
201229
```
202230

203-
### Customizing IPFS Cluster Upload Settings
204-
205-
When using IPFS Cluster, you can customize both the number of retry attempts and the timeout duration for uploads:
206-
207-
```yaml
208-
- name: Deploy to IPFS
209-
uses: ipfs/ipfs-deploy-action@v1
210-
with:
211-
# ... other inputs ...
212-
cluster-retry-attempts: '10' # Default is 5
213-
cluster-timeout-minutes: '5' # Default is 2
214-
```
215-
216-
These settings are particularly useful when:
217-
218-
- Dealing with larger files that need more time to upload
219-
- Working with slower or less reliable network connections
220-
- Need to adjust the balance between retry attempts and timeout duration
221231

222232
## Accessing Your Deployed Site
223233

@@ -231,6 +241,7 @@ Your site will be accessible through:
231241

232242
- [Storacha Gateway](https://docs.storacha.network/concepts/ipfs-gateways/): `https://<CID>.ipfs.w3s.link`
233243
- [Public Good Gateway](../concepts/public-utilities.md#public-ipfs-gateways): `https://<CID>.ipfs.dweb.link`
244+
- [Service Worker Gateway](https://inbrowser.link): `https://inbrowser.link/ipfs/<CID>`
234245

235246
## Troubleshooting
236247

@@ -241,8 +252,11 @@ Your site will be accessible through:
241252

242253
2. **Authentication Issues**
243254

244-
- Verify your Storacha key and proof are correctly set in GitHub secrets
255+
- Verify your credentials are correctly set in GitHub secrets
245256
- Check that the secrets are properly referenced in the workflow file
257+
- For Storacha, ensure both the key and proof are provided
258+
- For IPFS Cluster, ensure URL, username, and password are all provided
259+
- For Kubo, ensure both API URL and auth are provided
246260

247261
3. **Workflow Permission Issues**
248262
- Ensure the `permissions` block is included in your workflow
@@ -255,6 +269,7 @@ Your site will be accessible through:
255269
3. Consider using multiple IPFS providers for redundancy
256270
4. Use environment-specific configurations when needed
257271

272+
258273
## Getting Help
259274

260275
If you encounter any issues:

0 commit comments

Comments
 (0)