Guide on how to set up a DNSLink Gateway with Kubo and Caddy

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'

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.
 

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

docs/how-to/websites-on-ipfs/dnslink-gateway.md

@@ -0,0 +1,200 @@
+---
+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).
+---
+
+# Setup a DNSLink Gateway to serve static sites with Kubo and Caddy
+
+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](../../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](./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.
+
+## Goal
+
+By the end of this guide, you will have:
+
+- 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 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., `yourdomain.com`).
+- DNS configured for your domain:
+  - 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.
+
+## 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](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. [Config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaynofetch)
+
+    ```bash
+    ipfs config --json Gateway.NoFetch true
+    ```
+
+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
+    ```
+
+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 '{
+        "yourdomain.com": {
+          "NoDNSLink": false,
+          "Paths": []
+        }
+      }'
+    ```
+
+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 `yourdomain.com`.
+
+## Step 2: Configure Caddy
+
+### Set Up Caddy as a Reverse Proxy
+
+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:
+
+```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
+yourdomain.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:**
+
+- `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:
+
+```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 `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 `yourdomain.com`.
+
+3.  **Create a `TXT` record**:
+
+    - **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.yourdomain.com
+    # Expected Output: "dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze"
+
+    # Also verify your A record:
+    dig +short A yourdomain.com
+    # Expected Output: YOUR_SERVER_IP
+    ```
+
+> **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
+
+### 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://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`).
+
+## 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
+
+### 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).