How to Host a Static Website on IPFS (and Why Pin It)

Hosting a static site on IPFS looks deceptively simple in most tutorials: add a file, get a link, done. What those tutorials usually skip is the part that actually determines whether that site is still reachable next month. This article covers the full picture, from files to CID to a real, memorable URL, and the one step most quick-start guides leave out entirely.

TL;DR:

• Hosting a site on IPFS means adding its files, which produces a CID, and everything else, access, persistence, a real domain, builds on top of that one identifier
• IPFS's own documentation is direct about the gap this creates: "IPFS nodes treat the data they store like a cache," with no guarantee it stays available on its own
• A gateway is what makes the site loadable in a normal browser; DNSLink is what turns a raw CID into a real, memorable domain name
• Single-page apps need one extra consideration: client-side routing doesn't work the same way as it does on a traditional server, worth checking before assuming a React or Vue app will "just work"
• AIOZ Pin covers the two pieces a bare IPFS upload doesn't: guaranteed pinning so the site doesn't quietly disappear, and a dedicated gateway that isn't subject to shared public rate limits

What "Hosting on IPFS" Actually Means

There's no server to configure and no hosting account to set up in the traditional sense. Hosting a static site on IPFS means adding its files, index.html, CSS, JS, images, to the network, which produces a CID for the whole directory. That CID is now the site's permanent address: anyone with it can retrieve every file inside, reconstructed exactly. Everything past that point, how someone actually reaches the site through a browser, whether it stays available, whether it has a real domain, is a separate set of decisions layered on top of that one CID.

The Gap Most Quick-Start Guides Skip

IPFS's own guides are refreshingly honest about a specific limitation: "IPFS nodes treat the data they store like a cache, meaning that there is no guarantee the data will continue to be stored." A file added through a local node or a temporary tool can be added successfully, resolve correctly for a while, and then quietly become unreachable once nothing is actively keeping it around anymore. This is the exact problem pinning exists to solve, and it's worth treating as a required step, not an optional add-on, for any site meant to still be live next month.

Making It Loadable in a Normal Browser

A raw CID isn't something most visitors will ever see directly. A gateway translates a request for that CID into a standard HTTP response, so a normal browser loads the site the way it would load any other page, no special software required on the visitor's end. This series covers gateway mechanics, including the meaningful difference between a shared public gateway and a dedicated one, in full elsewhere; the short version relevant here is that gateway choice affects real-world reliability under actual traffic, not just whether the site technically loads once.

Giving It a Real Domain

A 46-character CID in the address bar isn't what most projects want visitors to see. DNSLink solves this by pointing a normal-looking domain at the site's current CID through a DNS TXT record, so visitors see a real, memorable domain instead of a raw gateway URL. Because DNSLink resolves independently of who's actually pinning the content, it also means the underlying CID can be updated (a new build, a bug fix) without visitors needing a new link, as long as the DNS record gets updated to match. Pairing DNSLink with an IPNS name, rather than pointing directly at a fixed CID, is the more flexible version of this same pattern, since it avoids touching DNS on every single deploy.

The Single-Page App Caveat

Traditional multi-page sites work on IPFS exactly as expected: each path corresponds to an actual file. Single-page applications, the kind built with React, Vue, or similar frameworks that handle routing client-side, need extra consideration. IPFS's own documentation flags this directly: basic hosting doesn't handle SPA-style routing, and projects needing it should look into redirects and custom 404 handling specifically, rather than assuming a client-side router will behave the same way it does on a conventional web server. Worth checking before deploying, not after a broken deep link gets reported.

Where AIOZ Pin Fits

Everything above describes the mechanism; AIOZ Pin is one concrete way to run it in production rather than assembling each piece manually. Uploading a site's build directory through pinFolderToIPFS() handles both gaps a bare IPFS add leaves open: the content gets pinned, not just cached, so it doesn't quietly disappear the way an unpinned upload can, and it becomes reachable through AIOZ Pin's dedicated gateway, which isn't subject to the rate limits a shared public gateway enforces under real traffic. DNSLink still sits on top as an independent step, since it's a general IPFS technique that doesn't require AIOZ Pin's involvement, but the pinning and gateway layer underneath it is exactly what a production static site actually needs to stay reliably online.

Frequently Asked Questions

Do I need to run my own IPFS node to host a website on it? No. Uploading through a pinning service's SDK, API, or desktop tool handles adding the files and producing a CID without requiring you to run or maintain node infrastructure yourself.

Why does a site I uploaded to IPFS sometimes stop loading later? Because IPFS nodes treat stored data like a cache by default, with no guarantee it stays available. If nothing is actively pinning the content, it can become unreachable once whatever originally hosted it stops.

How do I get a real domain instead of a raw CID for my IPFS site? DNSLink, a DNS TXT record that points a normal domain name at the site's current CID (or at an IPNS name, for a version that doesn't need updating on every deploy).

Does a React or Vue single-page app work on IPFS out of the box? Basic static hosting doesn't handle client-side routing the way a traditional server does. Check IPFS's redirects and custom-404 guidance specifically before assuming deep links will resolve correctly.

What does AIOZ Pin add on top of a basic IPFS upload? Guaranteed pinning, so the site doesn't quietly disappear once nothing else is hosting it, and a dedicated gateway that isn't subject to shared public rate limits under real traffic.

Related Reading

• Explore How IPFS Gateway Works Across Decentralized Networks - the full mechanics behind making a site loadable in a normal browser
• DNSLink: Pointing a Domain Name at IPFS Content - the full mechanics of the domain step summarized above
• IPNS: Mutable Pointers to Immutable IPFS Content - the update-without-a-new-link pattern mentioned above
• IPFS Garbage Collection: What Unpinning Actually Does - the mechanism behind why unpinned content actually disappears
• How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - the full product breakdown behind the pinning and gateway layer described above

References

• IPFS Docs: Host a Single-Page Website
• IPFS Docs: Address IPFS on the Web