tldr: cd your-website && npx @agentofuser/ipfs-deploy

This is going to be like the quickest tutorial ever. Underwhelming almost.

You don’t need to know anything about IPFS or distributed nothing, not even static site generators.

Ready? Ok, the first step is you gotta open up your terminal and type this in:

mkdir -p dwebsite/public

cd dwebsite

echo '<h1>Hello, worlds!</h1>' >> public/index.html yarn global add @agentofuser/ipfs-deploy

ipd

You with me? Ok, typed that. What else? Nothing.

What? Yep. You’re done here.

Now you sit back and watch as the victory parade logs by 😎

ℹ 🤔 No path argument specified. Looking for common ones...

✔ 📂 Found local public directory. Deploying that.

✔ 🚚 public weighs 24 B.

✔ 📌 It's pinned to Infura now with hash:

ℹ 🔗 QmQzKWGdjjQeTXrruYL2vLkCqRP8TyXnG1a9QEJjDM8WTY

✔ 📋 Copied HTTP gateway URL to clipboard:

ℹ 🔗 https://ipfs.infura.io/ipfs/QmQzKWGdjjQeTXrruYL2vLkCqRP8TyXnG1a9QEJjDM8WTY

✔ 🏄 Opened web browser (call with -O to disable.)

And there you have it. Your very own l33t #dwebsite live on the hashlinked Merkleverse. Check it out. Share with your friends.

Sweet, huh? 🍬

Slow down, what exactly just happened?

Alright, that was a bit much to take in at once. Let’s rewind a little and look at it in slow-motion, with backstage commentary:

1. Where’s the stuff?

Truth be told, I could have called ipd ./public , passing the directory to be deployed ( public ) explicitly.

But then you wouldn’t see the “hard thinking” emoji as ipfs-deploy probes smartly about for one of the many, often undocumented, build destinations commonly used by static site generators.

ℹ 🤔 No path argument specified. Looking for common ones...

✔ 📂 Found local public directory. Deploying that.

Yes, I actually combed through staticgen.com, installed a bunch of those static site generators, and built little test sites just so I could claim that “zero-config” headline. It’s the little things, you know.

This is what ipfs-deploy looks for when we’re too lazy to type it out:

const guesses = [

'_site', // jekyll, hakyll, eleventy

'site', // forgot which

'public', // gatsby, hugo

'dist', // nuxt

'output', // pelican

'out', // hexo

'build', // metalsmith, middleman

'website/build', // docusaurus

'docs', // many others

]

As you can see from this publication’s name, I’m a fan of Gatsby, but ipfs-deploy serves all in need. Bring your own SSG and we’ll slap an interplanetary jetpack on its back and send it flying. 🚀

2. The upload

This is what we’re here for, that is, putting the website into space (figuratively, for now). So a few seconds later, ipfs-deploy delivers:

✔ 📌 It's pinned to Infura now with hash:

ℹ 🔗 QmQzKWGdjjQeTXrruYL2vLkCqRP8TyXnG1a9QEJjDM8WTY

Jackpot! That’s the money shot right there.

That little rambling of a hash is the crux of the whole dweb judo. The magic utterance that summons by name your website from the cavernous depths of the connected dungeons, caring not where it lies, but only what it is.

Intrinsic addressing, unbound by location or route.

Welcome <grave pause> to the distributed future.

Wait a minute, I thought I heard you say “distributed” 🧐

Oh, you perspicacious reader.

You’re right: if IPFS is supposed to be a peer-to-peer protocol, why are we even uploading at all, right? To a server!?

Shouldn’t we just announce to the network that we have the hash and then wait to serve it ourselves to other peers as they request it?

Yeah, you can do that. Then you close your laptop, wifi goes down, 💩 happens, and poof ✨ there goes your website.

This is just like torrents: you need at least one seeder to be available for content to be reachable. If your website has tons of people who run their own IPFS node visiting it and re-serving it to others, then on average your uptime will be pretty high.

But there aren’t that many such visitors around yet (hopefully Brave will fix that for us) and besides, it’s a brand new website! 🐣 Poor thing wasn’t born famous. Give it some time.

It would be a different story if browsers had a decent #asyncUX and visitors could easily tell them to queue the download for when a peer is available and then notify when it’s ready (like a seamless “read it later” flow).

But as it stands, if there’s no one live the moment a request is made, things just hang and then time out. Definitely not space-ready.

So we need a high-uptime seeder on our side. Or, in IPFS lingo, a “pinner.”

Zero-Config Pinning with Infura.io

A big design goal of ipfs-deploy is to let you have that first happy experience of just seeing something you made up on IPFS as fast as possible.

One way to do that is to run a local IPFS daemon and have you serve the content yourself.

But as we saw above, that would be a little gimmicky as it doesn’t represent what an actual deployment that you can share with your friends would look like. Gotta have a stable pinner.

Pinning stuff with decent uptime costs money though, so most pinning services understandably require you to at least sign up for a free tier before they’ll agree to host your website.

Not Infura.io, though!

By some magic of careful rate-limiting, clever abuse prevention, growth capital, or reckless abandon, they let you just upload stuff out of the blue, unauthenticated, and they’ll serve it for you indefinitely. (Even against your will it seems, as there is no clear way of unpinning things at the moment.)

So we owe that slick on-ramp to their generosity: thank y’all at Infura, and please keep it up!

Also, if you own a pinning service yourself and would like to be part of the zero-config welcome package, please consider adding an “even freer” tier that doesn’t require signup.

Newly-created static websites don’t take up much room, have very little traffic, and are a great gateway into further IPFS consumption.

You did it! 🏁

If you got this far, condragulations. You rock! 🗿

Not only did you deploy your first IPFS website, you can now boast you actually understand how it works by waving your hands and saying “oh, it’s pretty much like git + bittorrent you know, easy peasy!”

If you diligently followed the instructions, and somehow things blew up in your face, that’s on me, not you. This is my commitment: your first happy experience, or it’s a bug!

So please tell me what went wrong and I’ll smooth it out for you.

We’re all about removing friction around here 🧹 🥌

If you haven’t had enough, stick around for some extra credit.

And if you are content with where we got for now, please share that feeling with others by spreading and upvoting this guide far and wide :) Thank you!