From b6d0586e0cce6bd49b32e86c43cbeb14a7378c01 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Thu, 3 Apr 2025 16:49:21 +0200 Subject: [PATCH 1/5] add guide for dnslink gateway --- .../websites-on-ipfs/dnslink-gateway.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 docs/how-to/websites-on-ipfs/dnslink-gateway.md diff --git a/docs/how-to/websites-on-ipfs/dnslink-gateway.md b/docs/how-to/websites-on-ipfs/dnslink-gateway.md new file mode 100644 index 000000000..68c568b6c --- /dev/null +++ b/docs/how-to/websites-on-ipfs/dnslink-gateway.md @@ -0,0 +1,194 @@ +--- +title: Serve static sites and apps with a DNSLink Gateway +description: Learn how to set up a DNSLink Gateway with Kubo and Caddy to serve IPFS content via your own domain including TLS (HTTPS). +--- + +# Serve static sites and apps with a DNSLink Gateway + +This guide explains how to host a static site or app on IPFS using a DNSLink Gateway. + +For this, you will use a dedicated DNSLink IPFS gateway using Kubo and Caddy to serve content via a standard domain name like `thelocalgardener.com` and resolving DNSLink. + +This allows users to access IPFS content through a known domain name without needing special browser extensions or users needing to know the specific Content Identifier (CID). The gateway automatically resolves the DNSLink TXT record associated with the domain, and fetches and serves the content of the CID. + +This guide assumes the CID of the site or app is already pinned to IPFS. If not, check out the [Deploy Static Apps to IPFS with GitHub Actions](./deploy-github-action.md) guide. + +## Goal + +By the end of this guide, you will have: + +- Your domain, e.g. `https://thelocalgardener.com`, serving the site or app specified in its DNSLink TXT record. +- A running Kubo IPFS node configured as a DNSLink gateway for `thelocalgardener.com`. +- A Caddy web server acting as a reverse proxy, handling TLS termination so that the site is served over HTTPS. + +## Prerequisites + +Before you start, ensure you have the following: + +- A server with a static public IP address (e.g., `YOUR_SERVER_IP`). +- Port 443 open on your server's firewall to allow HTTPS traffic. +- A domain name (e.g., `thelocalgardener.com`). +- DNS configured for your domain: + - An **`A` record** pointing `thelocalgardener.com` to your server's public IP address (`YOUR_SERVER_IP`). + - _(We will configure the required DNSLink `TXT` record later in the guide)._ +- Kubo installed and initialized on your server. +- Caddy installed on your server. + +## Step 1: Configure Kubo + +### Adjust Kubo Gateway Configuration + +First, you need to adjust the Kubo gateway configuration. These settings tell Kubo to act as a specific gateway for your domain and disable certain default behaviors, like fetching arbitrary CIDs. + +With this configuration, Kubo will match the domain in the [`host` header]() of requests that are proxied from Caddy, and if it matches the domain configured in this step, it will resolve the DNSLink TXT record and serve the content of the CID. + +#### Commands to Run + +1. **Disable fetching content for arbitrary CIDs**: + This prevents your gateway from being used as a general-purpose public gateway. + + ```bash + ipfs config --json Gateway.NoFetch true + ``` + +1. **Disable DNSLink resolution globally (default)**: + You'll enable it only for your specific domain in the next step. + + ```bash + ipfs config --json Gateway.NoDNSLink true + ``` + +1. **Enable DNSLink for `thelocalgardener.com`**: + This explicitly allows DNSLink resolution _only_ for requests hitting this hostname. + + ```bash + ipfs config --json Gateway.PublicGateways '{ + "thelocalgardener.com": { + "NoDNSLink": false, + "Paths": [] + } + }' + ``` + +1. **Restart the Kubo daemon** for the changes to take effect: + ```bash + systemctl restart ipfs + ``` + +These commands modify the `config` file in your IPFS repository (usually `~/.ipfs/config`). The `Gateway.PublicGateways` setting defines specific configurations for different hostnames. Here, you override the global `NoDNSLink` setting specifically for `thelocalgardener.com`. + +## Step 2: Configure Caddy + +### Set Up Caddy as a Reverse Proxy + +Next, configure Caddy to handle incoming HTTPS requests for `thelocalgardener.com` and proxy them to the Kubo gateway, which is listening by default on `127.0.0.1:8080`. + +To check this, you can run the following command: + +```bash +cat /data/kubo/config | jq .Addresses.Gateway +``` + +You should see something like this: + +```json +"/ip4/127.0.0.1/tcp/8080" +``` + +This means that the Kubo gateway is listening on `127.0.0.1:8080`. + +#### Caddyfile Configuration + +Create or edit your `Caddyfile` (usually located at `/etc/caddy/Caddyfile` or in your current directory if running Caddy manually) with the following content: + +```caddy +thelocalgardener.com { + # Caddy automatically handles HTTPS provisioning for your domain + + # Proxy all requests to the local Kubo gateway + reverse_proxy localhost:8080 + + # Optional: Configure logging + log { + output stdout + format json + level INFO + } +} +``` + +**Explanation:** + +- `thelocalgardener.com { ... }`: Defines a site block for your domain. Caddy will automatically obtain and renew a TLS certificate for it, provided the `A` record DNS is set correctly. +- `reverse_proxy localhost:8080`: Forwards all incoming requests for `thelocalgardener.com` to the Kubo daemon listening on port 8080. +- `log { ... }`: Configures access logging (optional but recommended). + +**Start or reload Caddy** for the configuration to apply: + +```bash +# If using systemd: +sudo systemctl reload caddy + +# Or, if running Caddy manually in the directory with the Caddyfile: +caddy run +``` + +## Step 3: Set up DNSLink TXT Record + +### Configure DNSLink DNS Record + +Now, you will create the DNSLink `TXT` record for your domain to point to CID of the site or app you want to serve, which is necessary in addition to the `A` record pointing to your server's IP address. + +When requests are made to `thelocalgardener.com`, the DNSLink gateway will automatically resolve the DNSLink TXT record, retrieve the data from providers (unless the data is already pinned to your IPFS node) and serve the content of the CID. + +#### Steps to Create a TXT Record + +1. **Get the CID** of the content you want to serve. + +2. **Go to your DNS provider's dashboard** for `thelocalgardener.com`. + +3. **Create a `TXT` record**: + + - **Name/Host**: `_dnslink.thelocalgardener` (or `_dnslink.thelocalgardener.com` depending on your provider's interface) + - **Type**: `TXT` + - **Value/Content**: `dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze` (Replace the example CID with your actual CID) + + **Note:** The record name _must_ start with `_dnslink.`. DNS propagation might take some time.. You can check if it has propagated using tools like `dig` or `nslookup`: + + ```bash + dig +short TXT _dnslink.thelocalgardener.com + # Expected Output: "dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze" + + # Also verify your A record: + dig +short A thelocalgardener.com + # Expected Output: YOUR_SERVER_IP + ``` + +> **Note:** The DNSLink record will need to be updated everytime you update the site or app, leading to a new CID for the build. In order to automate this, you can use the [DNSLink GitHub Action](https://github.com/ipshipyard/dnslink-action), as part of your CI/CD pipeline. + +## Step 4: Verify + +### Ensure Everything is Working + +Once both DNS records (`A` and `TXT`) have propagated and both Kubo and Caddy are running with the correct configurations: + +1. Open your web browser and navigate to that domain, e.g. `https://thelocalgardener.com`. +2. You should see the content associated with your CID served securely over HTTPS via your Caddy server, which fetched it from your Kubo node using the DNSLink record. + +Your gateway will now automatically serve the content specified in the `_dnslink.thelocalgardener.com` TXT record. To update the site, simply pin the new version to IPFS, get the new CID, and update the `TXT` record's value with the new CID path (`dnslink=/ipfs/NEW_CID_HERE`). + +## Troubleshooting + +### Common Issues and Solutions + +- **DNS Propagation Delays**: If your domain isn't resolving, check the DNS settings and ensure the records have propagated. Use `dig` or `nslookup` to verify. +- **Caddy Configuration Errors**: Ensure your `Caddyfile` syntax is correct. Check Caddy logs for any errors. +- **IPFS Node Issues**: Make sure your IPFS node is running and accessible. Restart the daemon if necessary. + +## Summary + +You've successfully set up a DNSLink Gateway using Kubo and Caddy to serve IPFS content via your domain. Keep your software updated and monitor your server for any issues. For further customization, refer to the [Kubo config documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md) and [Caddy documentation](https://caddyserver.com/docs). + +## Feedback + +We'd love to hear your thoughts on this guide. If you have suggestions or encounter issues, please let us know to help improve future versions. From eeba85ce13ceab422fde065a04834d65e51bc017 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Thu, 3 Apr 2025 17:19:20 +0200 Subject: [PATCH 2/5] typos --- docs/how-to/websites-on-ipfs/dnslink-gateway.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/websites-on-ipfs/dnslink-gateway.md b/docs/how-to/websites-on-ipfs/dnslink-gateway.md index 68c568b6c..16389d2b0 100644 --- a/docs/how-to/websites-on-ipfs/dnslink-gateway.md +++ b/docs/how-to/websites-on-ipfs/dnslink-gateway.md @@ -153,7 +153,7 @@ When requests are made to `thelocalgardener.com`, the DNSLink gateway will autom - **Type**: `TXT` - **Value/Content**: `dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze` (Replace the example CID with your actual CID) - **Note:** The record name _must_ start with `_dnslink.`. DNS propagation might take some time.. You can check if it has propagated using tools like `dig` or `nslookup`: + **Note:** The record name _must_ start with `_dnslink.`. DNS propagation might take some time. You can check if it has propagated using tools like `dig` or `nslookup`: ```bash dig +short TXT _dnslink.thelocalgardener.com @@ -164,7 +164,7 @@ When requests are made to `thelocalgardener.com`, the DNSLink gateway will autom # Expected Output: YOUR_SERVER_IP ``` -> **Note:** The DNSLink record will need to be updated everytime you update the site or app, leading to a new CID for the build. In order to automate this, you can use the [DNSLink GitHub Action](https://github.com/ipshipyard/dnslink-action), as part of your CI/CD pipeline. +> **Note:** The DNSLink record will need to be updated every time you update the site or app, leading to a new CID for the build. In order to automate this, you can use the [DNSLink GitHub Action](https://github.com/ipshipyard/dnslink-action), as part of your CI/CD pipeline. ## Step 4: Verify From eabce2efb0a814c497883ccc70d15e74545a1fe5 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 4 Apr 2025 14:07:31 +0200 Subject: [PATCH 3/5] add sidebar link and interlink guide --- docs/.vuepress/config.js | 1 + .../how-to/websites-on-ipfs/custom-domains.md | 4 +- .../websites-on-ipfs/deploy-github-action.md | 4 +- .../websites-on-ipfs/dnslink-gateway.md | 78 ++++++++++--------- 4 files changed, 47 insertions(+), 40 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 347a6a9ff..326535cfa 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -244,6 +244,7 @@ module.exports = { '/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/dnslink-gateway', '/how-to/websites-on-ipfs/multipage-website', '/how-to/websites-on-ipfs/static-site-generators', '/how-to/websites-on-ipfs/redirects-and-custom-404s' diff --git a/docs/how-to/websites-on-ipfs/custom-domains.md b/docs/how-to/websites-on-ipfs/custom-domains.md index da61cc493..6b7046dd5 100644 --- a/docs/how-to/websites-on-ipfs/custom-domains.md +++ b/docs/how-to/websites-on-ipfs/custom-domains.md @@ -20,7 +20,7 @@ The main difference between the two options is that CID signaling with DNSLink i 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 +## 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). @@ -40,7 +40,7 @@ With this approach, users can access your website via a custom domain name, e.g. 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. +1. Self-host both the IPFS provider (e.g. [Kubo](https://github.com/ipfs/kubo)) and the IPFS HTTP gateway (e.g. [Kubo](https://github.com/ipfs/kubo)). 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. [See the guide on setting up a DNSLink gateway](./dnslink-gateway.md) for more details. 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 index 2400d3d03..077d54876 100644 --- a/docs/how-to/websites-on-ipfs/deploy-github-action.md +++ b/docs/how-to/websites-on-ipfs/deploy-github-action.md @@ -1,11 +1,11 @@ --- -title: Deploy Static Apps to IPFS with GitHub Actions +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.1 current-ipfs-cluster-version: v1.1.2 --- -# Deploy Static Apps to IPFS with GitHub Actions +# 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/ipshipyard/ipfs-deploy-action). diff --git a/docs/how-to/websites-on-ipfs/dnslink-gateway.md b/docs/how-to/websites-on-ipfs/dnslink-gateway.md index 16389d2b0..6899ce63d 100644 --- a/docs/how-to/websites-on-ipfs/dnslink-gateway.md +++ b/docs/how-to/websites-on-ipfs/dnslink-gateway.md @@ -1,15 +1,15 @@ --- -title: Serve static sites and apps with a DNSLink Gateway +title: Setup a DNSLink Gateway to serve static sites with Kubo description: Learn how to set up a DNSLink Gateway with Kubo and Caddy to serve IPFS content via your own domain including TLS (HTTPS). --- -# Serve static sites and apps with a DNSLink Gateway +# Setup a DNSLink Gateway to serve static sites with Kubo and Caddy -This guide explains how to host a static site or app on IPFS using a DNSLink Gateway. +This guide explains how to serve a static site or app on IPFS using a DNSLink Gateway. -For this, you will use a dedicated DNSLink IPFS gateway using Kubo and Caddy to serve content via a standard domain name like `thelocalgardener.com` and resolving DNSLink. +For this, you will use a dedicated DNSLink IPFS gateway using [Kubo](../../install/command-line.md) and [Caddy](https://github.com/caddyserver/caddy) to serve content over HTTPS via a custom domain name. -This allows users to access IPFS content through a known domain name without needing special browser extensions or users needing to know the specific Content Identifier (CID). The gateway automatically resolves the DNSLink TXT record associated with the domain, and fetches and serves the content of the CID. +This allows users to access [IPFS content through a known domain name without needing special browser extensions](./custom-domains.md) or users needing to know the specific Content Identifier (CID). The gateway automatically resolves the [DNSLink](../../concepts/dnslink.md) TXT record associated with the domain to CID, and fetches and serves the content of the CID. This guide assumes the CID of the site or app is already pinned to IPFS. If not, check out the [Deploy Static Apps to IPFS with GitHub Actions](./deploy-github-action.md) guide. @@ -17,20 +17,26 @@ This guide assumes the CID of the site or app is already pinned to IPFS. If not, By the end of this guide, you will have: -- Your domain, e.g. `https://thelocalgardener.com`, serving the site or app specified in its DNSLink TXT record. -- A running Kubo IPFS node configured as a DNSLink gateway for `thelocalgardener.com`. +- Your domain, e.g. `https://yourdomain.com`, serving the site or app specified in its DNSLink TXT record. +- A running Kubo IPFS node configured as a DNSLink gateway for `yourdomain.com`. - A Caddy web server acting as a reverse proxy, handling TLS termination so that the site is served over HTTPS. +## Note about verification + +Note that the DNSLink gateway you will configure will function as a _trusted gateway_, in the sense that the readers trust the server your domain points to to serve the correct content, without verifying the content. As such, it assumes the same security assumptions and [risks of the web](https://blog.ipfs.tech/2025-could-ipfs-prevent-bybit-hack/). + +This may be fine for your use-case. However, if the site or app you are deploying requires more security and less trust, we recommend your users to use a verifying IPFS client by viewing your site using a local IPFS Node like Kubo or using the [Service Worker Gateway](https://github.com/ipfs/service-worker-gateway) to load the site while also verifying the content matches the CID in the DNSLink TXT record. + ## Prerequisites Before you start, ensure you have the following: - A server with a static public IP address (e.g., `YOUR_SERVER_IP`). - Port 443 open on your server's firewall to allow HTTPS traffic. -- A domain name (e.g., `thelocalgardener.com`). +- A domain name (e.g., `yourdomain.com`). - DNS configured for your domain: - - An **`A` record** pointing `thelocalgardener.com` to your server's public IP address (`YOUR_SERVER_IP`). - - _(We will configure the required DNSLink `TXT` record later in the guide)._ + - An **`A` record** pointing `yourdomain.com` to your server's public IP address (`YOUR_SERVER_IP`). + - _(We will configure the required [DNSLink](./custom-domains.md#cid-signaling-with-dnslink) `TXT` record later in the guide)._ - Kubo installed and initialized on your server. - Caddy installed on your server. @@ -40,48 +46,48 @@ Before you start, ensure you have the following: First, you need to adjust the Kubo gateway configuration. These settings tell Kubo to act as a specific gateway for your domain and disable certain default behaviors, like fetching arbitrary CIDs. -With this configuration, Kubo will match the domain in the [`host` header]() of requests that are proxied from Caddy, and if it matches the domain configured in this step, it will resolve the DNSLink TXT record and serve the content of the CID. +With this configuration, Kubo will match the domain in the [`host` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Host) of requests that are proxied from Caddy, and if it matches the domain configured in this step, it will resolve the DNSLink TXT record and serve the content of the CID. #### Commands to Run -1. **Disable fetching content for arbitrary CIDs**: - This prevents your gateway from being used as a general-purpose public gateway. +1. **Disable fetching content for arbitrary CIDs**: + This prevents your gateway from being used as a general-purpose public gateway. [Config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaynofetch) ```bash ipfs config --json Gateway.NoFetch true ``` -1. **Disable DNSLink resolution globally (default)**: - You'll enable it only for your specific domain in the next step. +2. **Disable DNSLink resolution globally (default)**: + You'll enable it only for your specific domain in the next step. [Config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaynodnslink) ```bash ipfs config --json Gateway.NoDNSLink true ``` -1. **Enable DNSLink for `thelocalgardener.com`**: - This explicitly allows DNSLink resolution _only_ for requests hitting this hostname. +3. **Enable DNSLink for `yourdomain.com`**: + This explicitly allows DNSLink resolution _only_ for requests hitting this hostname. [Config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaypublicgateways) ```bash ipfs config --json Gateway.PublicGateways '{ - "thelocalgardener.com": { + "yourdomain.com": { "NoDNSLink": false, "Paths": [] } }' ``` -1. **Restart the Kubo daemon** for the changes to take effect: +4. **Restart the Kubo daemon** for the changes to take effect: ```bash systemctl restart ipfs ``` -These commands modify the `config` file in your IPFS repository (usually `~/.ipfs/config`). The `Gateway.PublicGateways` setting defines specific configurations for different hostnames. Here, you override the global `NoDNSLink` setting specifically for `thelocalgardener.com`. +These commands modify the `config` file in your IPFS repository (usually `~/.ipfs/config`). The `Gateway.PublicGateways` setting defines specific configurations for different hostnames. Here, you override the global `NoDNSLink` setting specifically for `yourdomain.com`. ## Step 2: Configure Caddy ### Set Up Caddy as a Reverse Proxy -Next, configure Caddy to handle incoming HTTPS requests for `thelocalgardener.com` and proxy them to the Kubo gateway, which is listening by default on `127.0.0.1:8080`. +Next, configure Caddy to handle incoming HTTPS requests for `yourdomain.com` and proxy them to the Kubo gateway, which is listening by default on `127.0.0.1:8080`. To check this, you can run the following command: @@ -102,7 +108,7 @@ This means that the Kubo gateway is listening on `127.0.0.1:8080`. Create or edit your `Caddyfile` (usually located at `/etc/caddy/Caddyfile` or in your current directory if running Caddy manually) with the following content: ```caddy -thelocalgardener.com { +yourdomain.com { # Caddy automatically handles HTTPS provisioning for your domain # Proxy all requests to the local Kubo gateway @@ -119,8 +125,8 @@ thelocalgardener.com { **Explanation:** -- `thelocalgardener.com { ... }`: Defines a site block for your domain. Caddy will automatically obtain and renew a TLS certificate for it, provided the `A` record DNS is set correctly. -- `reverse_proxy localhost:8080`: Forwards all incoming requests for `thelocalgardener.com` to the Kubo daemon listening on port 8080. +- `yourdomain.com { ... }`: Defines a site block for your domain. Caddy will automatically obtain and renew a TLS certificate for it, provided the `A` record DNS is set correctly. +- `reverse_proxy localhost:8080`: Forwards all incoming requests for `yourdomain.com` to the Kubo daemon listening on port 8080. - `log { ... }`: Configures access logging (optional but recommended). **Start or reload Caddy** for the configuration to apply: @@ -139,28 +145,28 @@ caddy run Now, you will create the DNSLink `TXT` record for your domain to point to CID of the site or app you want to serve, which is necessary in addition to the `A` record pointing to your server's IP address. -When requests are made to `thelocalgardener.com`, the DNSLink gateway will automatically resolve the DNSLink TXT record, retrieve the data from providers (unless the data is already pinned to your IPFS node) and serve the content of the CID. +When requests are made to `yourdomain.com`, the DNSLink gateway will automatically resolve the DNSLink TXT record, retrieve the data from providers (unless the data is already pinned to your IPFS node) and serve the content of the CID. #### Steps to Create a TXT Record 1. **Get the CID** of the content you want to serve. -2. **Go to your DNS provider's dashboard** for `thelocalgardener.com`. +2. **Go to your DNS provider's dashboard** for `yourdomain.com`. 3. **Create a `TXT` record**: - - **Name/Host**: `_dnslink.thelocalgardener` (or `_dnslink.thelocalgardener.com` depending on your provider's interface) + - **Name/Host**: `_dnslink.yourdomain` (or `_dnslink.yourdomain.com` depending on your provider's interface) - **Type**: `TXT` - **Value/Content**: `dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze` (Replace the example CID with your actual CID) **Note:** The record name _must_ start with `_dnslink.`. DNS propagation might take some time. You can check if it has propagated using tools like `dig` or `nslookup`: ```bash - dig +short TXT _dnslink.thelocalgardener.com + dig +short TXT _dnslink.yourdomain.com # Expected Output: "dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze" # Also verify your A record: - dig +short A thelocalgardener.com + dig +short A yourdomain.com # Expected Output: YOUR_SERVER_IP ``` @@ -172,10 +178,14 @@ When requests are made to `thelocalgardener.com`, the DNSLink gateway will autom Once both DNS records (`A` and `TXT`) have propagated and both Kubo and Caddy are running with the correct configurations: -1. Open your web browser and navigate to that domain, e.g. `https://thelocalgardener.com`. -2. You should see the content associated with your CID served securely over HTTPS via your Caddy server, which fetched it from your Kubo node using the DNSLink record. +1. Open your web browser and navigate to that domain, e.g. `https://yourdomain.com`. +2. You should see the content associated with your CID served securely over HTTPS via your Caddy server, which fetched it from your Kubo node using the DNSLink record. + +Your gateway will now automatically serve the content specified in the `_dnslink.yourdomain.com` TXT record. To update the site, simply pin the new version to IPFS, get the new CID, and update the `TXT` record's value with the new CID path (`dnslink=/ipfs/NEW_CID_HERE`). -Your gateway will now automatically serve the content specified in the `_dnslink.thelocalgardener.com` TXT record. To update the site, simply pin the new version to IPFS, get the new CID, and update the `TXT` record's value with the new CID path (`dnslink=/ipfs/NEW_CID_HERE`). +## Automate DNSLink Updates + +Depending on how you deploy your site, you can automate DNSLink updates using the [DNSLink GitHub Action](https://github.com/ipshipyard/dnslink-action), as part of your CI/CD pipeline, or other DNS management tools like [dnscontrol](https://github.com/StackExchange/dnscontrol) or [octodns](https://github.com/octodns/octodns). ## Troubleshooting @@ -188,7 +198,3 @@ Your gateway will now automatically serve the content specified in the `_dnslink ## Summary You've successfully set up a DNSLink Gateway using Kubo and Caddy to serve IPFS content via your domain. Keep your software updated and monitor your server for any issues. For further customization, refer to the [Kubo config documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md) and [Caddy documentation](https://caddyserver.com/docs). - -## Feedback - -We'd love to hear your thoughts on this guide. If you have suggestions or encounter issues, please let us know to help improve future versions. From e4d8bfd0f07a0ec3289096e8631b630751a01bcc Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 4 Apr 2025 14:15:56 +0200 Subject: [PATCH 4/5] fix typo --- docs/how-to/websites-on-ipfs/dnslink-gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/websites-on-ipfs/dnslink-gateway.md b/docs/how-to/websites-on-ipfs/dnslink-gateway.md index 6899ce63d..fe8db4bee 100644 --- a/docs/how-to/websites-on-ipfs/dnslink-gateway.md +++ b/docs/how-to/websites-on-ipfs/dnslink-gateway.md @@ -23,7 +23,7 @@ By the end of this guide, you will have: ## Note about verification -Note that the DNSLink gateway you will configure will function as a _trusted gateway_, in the sense that the readers trust the server your domain points to to serve the correct content, without verifying the content. As such, it assumes the same security assumptions and [risks of the web](https://blog.ipfs.tech/2025-could-ipfs-prevent-bybit-hack/). +Note that the DNSLink gateway you will configure will function as a _trusted gateway_, in the sense that the readers trust the server your domain points to serve the correct content, without verifying the content. As such, it assumes the same security assumptions and [risks of the web](https://blog.ipfs.tech/2025-could-ipfs-prevent-bybit-hack/). This may be fine for your use-case. However, if the site or app you are deploying requires more security and less trust, we recommend your users to use a verifying IPFS client by viewing your site using a local IPFS Node like Kubo or using the [Service Worker Gateway](https://github.com/ipfs/service-worker-gateway) to load the site while also verifying the content matches the CID in the DNSLink TXT record. From 61b9eb82fbfbabeb5a7103bc812c7d048e7b27f8 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 4 Apr 2025 14:25:14 +0200 Subject: [PATCH 5/5] add more allowed words to dictionary --- .github/styles/pln-ignore.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt index 1eb4e62ab..b07cb004c 100644 --- a/.github/styles/pln-ignore.txt +++ b/.github/styles/pln-ignore.txt @@ -63,6 +63,7 @@ dhts dialable dns('s) dnsaddr +dnscontrol dnslink dotgraph dups @@ -177,6 +178,7 @@ nfts nginx nodejs npm +octodns packfile passthrough peergos