|
| 1 | +--- |
| 2 | +title: Setup a DNSLink Gateway to serve static sites with Kubo |
| 3 | +description: Learn how to set up a DNSLink Gateway with Kubo and Caddy to serve IPFS content via your own domain including TLS (HTTPS). |
| 4 | +--- |
| 5 | + |
| 6 | +# Setup a DNSLink Gateway to serve static sites with Kubo and Caddy |
| 7 | + |
| 8 | +This guide explains how to serve a static site or app on IPFS using a DNSLink Gateway. |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +## Goal |
| 17 | + |
| 18 | +By the end of this guide, you will have: |
| 19 | + |
| 20 | +- Your domain, e.g. `https://yourdomain.com`, serving the site or app specified in its DNSLink TXT record. |
| 21 | +- A running Kubo IPFS node configured as a DNSLink gateway for `yourdomain.com`. |
| 22 | +- A Caddy web server acting as a reverse proxy, handling TLS termination so that the site is served over HTTPS. |
| 23 | + |
| 24 | +## Note about verification |
| 25 | + |
| 26 | +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/). |
| 27 | + |
| 28 | +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. |
| 29 | + |
| 30 | +## Prerequisites |
| 31 | + |
| 32 | +Before you start, ensure you have the following: |
| 33 | + |
| 34 | +- A server with a static public IP address (e.g., `YOUR_SERVER_IP`). |
| 35 | +- Port 443 open on your server's firewall to allow HTTPS traffic. |
| 36 | +- A domain name (e.g., `yourdomain.com`). |
| 37 | +- DNS configured for your domain: |
| 38 | + - An **`A` record** pointing `yourdomain.com` to your server's public IP address (`YOUR_SERVER_IP`). |
| 39 | + - _(We will configure the required [DNSLink](./custom-domains.md#cid-signaling-with-dnslink) `TXT` record later in the guide)._ |
| 40 | +- Kubo installed and initialized on your server. |
| 41 | +- Caddy installed on your server. |
| 42 | + |
| 43 | +## Step 1: Configure Kubo |
| 44 | + |
| 45 | +### Adjust Kubo Gateway Configuration |
| 46 | + |
| 47 | +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. |
| 48 | + |
| 49 | +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. |
| 50 | + |
| 51 | +#### Commands to Run |
| 52 | + |
| 53 | +1. **Disable fetching content for arbitrary CIDs**: |
| 54 | + 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) |
| 55 | + |
| 56 | + ```bash |
| 57 | + ipfs config --json Gateway.NoFetch true |
| 58 | + ``` |
| 59 | + |
| 60 | +2. **Disable DNSLink resolution globally (default)**: |
| 61 | + 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) |
| 62 | +
|
| 63 | + ```bash |
| 64 | + ipfs config --json Gateway.NoDNSLink true |
| 65 | + ``` |
| 66 | +
|
| 67 | +3. **Enable DNSLink for `yourdomain.com`**: |
| 68 | + This explicitly allows DNSLink resolution _only_ for requests hitting this hostname. [Config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaypublicgateways) |
| 69 | +
|
| 70 | + ```bash |
| 71 | + ipfs config --json Gateway.PublicGateways '{ |
| 72 | + "yourdomain.com": { |
| 73 | + "NoDNSLink": false, |
| 74 | + "Paths": [] |
| 75 | + } |
| 76 | + }' |
| 77 | + ``` |
| 78 | +
|
| 79 | +4. **Restart the Kubo daemon** for the changes to take effect: |
| 80 | + ```bash |
| 81 | + systemctl restart ipfs |
| 82 | + ``` |
| 83 | +
|
| 84 | +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`. |
| 85 | +
|
| 86 | +## Step 2: Configure Caddy |
| 87 | +
|
| 88 | +### Set Up Caddy as a Reverse Proxy |
| 89 | +
|
| 90 | +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`. |
| 91 | +
|
| 92 | +To verify that the gateway exposed by Kubo is listening, you can run the following command: |
| 93 | +
|
| 94 | +```bash |
| 95 | +cat /data/kubo/config | jq .Addresses.Gateway |
| 96 | +``` |
| 97 | +
|
| 98 | +You should see something like this: |
| 99 | +
|
| 100 | +```json |
| 101 | +"/ip4/127.0.0.1/tcp/8080" |
| 102 | +``` |
| 103 | +
|
| 104 | +This confirms that the gateway exposed by Kubo is listening on `127.0.0.1:8080`. |
| 105 | +
|
| 106 | +#### Caddyfile Configuration |
| 107 | +
|
| 108 | +Create or edit your `Caddyfile` (usually located at `/etc/caddy/Caddyfile` or in your current directory if running Caddy manually) with the following content: |
| 109 | +
|
| 110 | +```caddy |
| 111 | +yourdomain.com { |
| 112 | + # Caddy automatically handles HTTPS provisioning for your domain |
| 113 | +
|
| 114 | + # Proxy all requests to the local Kubo gateway |
| 115 | + reverse_proxy localhost:8080 |
| 116 | +
|
| 117 | + # Optional: Configure logging |
| 118 | + log { |
| 119 | + output stdout |
| 120 | + format json |
| 121 | + level INFO |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
| 125 | +
|
| 126 | +**Explanation:** |
| 127 | +
|
| 128 | +- `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. |
| 129 | +- `reverse_proxy localhost:8080`: Forwards all incoming requests for `yourdomain.com` to the Kubo daemon listening on port 8080. |
| 130 | +- `log { ... }`: Configures access logging (optional but recommended). |
| 131 | +
|
| 132 | +**Start or reload Caddy** for the configuration to apply: |
| 133 | +
|
| 134 | +```bash |
| 135 | +# If using systemd: |
| 136 | +sudo systemctl reload caddy |
| 137 | +
|
| 138 | +# Or, if running Caddy manually in the directory with the Caddyfile: |
| 139 | +caddy run |
| 140 | +``` |
| 141 | +
|
| 142 | +## Step 3: Set up DNSLink TXT Record |
| 143 | +
|
| 144 | +### Configure DNSLink DNS Record |
| 145 | +
|
| 146 | +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. |
| 147 | + |
| 148 | +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. |
| 149 | + |
| 150 | +#### Steps to Create a TXT Record |
| 151 | + |
| 152 | +1. **Get the CID** of the content you want to serve. |
| 153 | + |
| 154 | +2. **Go to your DNS provider's dashboard** for `yourdomain.com`. |
| 155 | +
|
| 156 | +3. **Create a `TXT` record**: |
| 157 | +
|
| 158 | + - **Name/Host**: `_dnslink.yourdomain` (or `_dnslink.yourdomain.com` depending on your provider's interface) |
| 159 | + - **Type**: `TXT` |
| 160 | + - **Value/Content**: `dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze` (Replace the example CID with your actual CID) |
| 161 | + |
| 162 | + **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`: |
| 163 | + |
| 164 | + ```bash |
| 165 | + dig +short TXT _dnslink.yourdomain.com |
| 166 | + # Expected Output: "dnslink=/ipfs/bafybeiay2koog2jnndn5gr2raytxh7evobry5lo2w4s7nhugc7xipy6aze" |
| 167 | +
|
| 168 | + # Also verify your A record: |
| 169 | + dig +short A yourdomain.com |
| 170 | + # Expected Output: YOUR_SERVER_IP |
| 171 | + ``` |
| 172 | + |
| 173 | +> **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. |
| 174 | + |
| 175 | +## Step 4: Verify |
| 176 | + |
| 177 | +### Ensure Everything is Working |
| 178 | + |
| 179 | +Once both DNS records (`A` and `TXT`) have propagated and both Kubo and Caddy are running with the correct configurations: |
| 180 | + |
| 181 | +1. Open your web browser and navigate to that domain, e.g. `https://yourdomain.com`. |
| 182 | +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. |
| 183 | + |
| 184 | +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`). |
| 185 | +
|
| 186 | +## Automate DNSLink Updates |
| 187 | +
|
| 188 | +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). |
| 189 | +
|
| 190 | +## Troubleshooting |
| 191 | +
|
| 192 | +### Common Issues and Solutions |
| 193 | +
|
| 194 | +- **DNS Propagation Delays**: If your domain isn't resolving, check the DNS settings and ensure the DNSLink record has propagated. You can use `dig` to verify: |
| 195 | + |
| 196 | + ```bash |
| 197 | + dig +short TXT _dnslink.yourdomain.com |
| 198 | + # Expected Output: "dnslink=/ipfs/bafy..." |
| 199 | + ``` |
| 200 | + |
| 201 | +- **Caddy Configuration Errors**: Ensure your `Caddyfile` syntax is correct. Check Caddy logs for any errors. |
| 202 | +- **IPFS Node Issues**: Make sure your IPFS node is running and accessible. Restart the daemon if necessary. |
| 203 | + |
| 204 | +## Summary |
| 205 | + |
| 206 | +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). |
0 commit comments