Upload static website to IPFS pinning services and optionally update DNS.
The goal of @agentofuser/ipfs-deploy is to make it as easy as possible to
deploy a static website to IPFS.
Table of Contents
Install
npm install -g @agentofuser/ipfs-deploy
Or
yarn global add @agentofuser/ipfs-deploy
You can call it either as ipd or as ipfs-deploy:
ipd public/
ipfs-deploy public/
No install:
You can run it directly with npx
without needing to install anything:
npx @agentofuser/ipfs-deploy _site
It will deploy to a public pinning service and give you a link to
ipfs.io/ipfs/your-hash so you can check it out.
Usage
You can get started just by typing out ipd and it will have smart defaults.
It deploys to a service that doesn’t need signup and gives you a link like
ipfs.io/ipfs/hash that you can use to see if everything went ok.
When you don’t specify a path argument to deploy, ipfs-deploy tries to
guess it for you based on the build directories used by the most popular static
site generators:
const guesses = [
'_site', // jekyll, hakyll
'site',
'public', // gatsby, hugo
'dist', // nuxt
'output', // pelican
'out', // hexo
'build', // metalsmith, middleman
'website/build', // docusaurus
'docs',
]
The --help option has some additional usage examples:
Examples:
ipfs-deploy # Deploys relative path "public" to
ipfs.infura.io/ipfs/hash; doesn't
update DNS; copies and opens URL.
These defaults are chosen so as not
to require signing up for any
service or setting up environment
variables on default use.
ipfs-deploy -p pinata _site # Deploys path "_site" ONLY to
pinata and doesn't update DNS
ipfs-deploy -p infura -p pinata -d # Deploys path "public" to pinata
cloudflare and infura, and updates cloudflare
DNS
To use Pinata and Cloudflare you need to sign up for those services. You can
read up on that over at:
https://www.cloudflare.com/distributed-web-gateway
and:
https://pinata.cloud/documentation#GettingStarted
(Infura doesn’t require creating an account and is therefore the default
pinning service used.)
After setting up your Cloudflare and Pinata accounts, in your website’s
repository root, create or edit the file .env with your domain and
credentials:
IPFS_DEPLOY_SITE_DOMAIN=
IPFS_DEPLOY_PINATA__API_KEY=
IPFS_DEPLOY_PINATA__SECRET_API_KEY=
IPFS_DEPLOY_CLOUDFLARE__API_EMAIL=
IPFS_DEPLOY_CLOUDFLARE__API_KEY=
(Don’t commit it to source control unless you know what you’re doing.)
$ echo '.env' >> .gitignore
Assuming your website’s production build is at the public subdirectory
(that’s what Gatsby and Hugo use; Jekyll and Hakyll use _site), run this at
the project’s root:
To see more details about command line usage, run:
You can optionally add a deploy command to your package.json:
// ⋮
"scripts": {
// ⋮
"deploy": "npx @agentofuser/ipfs-daemon public",
// ⋮
}
// ⋮
Then to run it, execute:
API
This is still pretty unstable and subject to change, so I will just show how
the executable currently uses the API.
const deploy = require('@agentofuser/ipfs-deploy')
;(async () => {
try {
const deployOptions = {
publicDirPath: argv.path,
copyPublicGatewayUrlToClipboard: !argv.noClipboard,
open: !argv.O,
remotePinners: argv.p,
dnsProviders: argv.d,
siteDomain: argv.siteDomain,
credentials: {
cloudflare: {
apiKey: argv.cloudflare && argv.cloudflare.apiKey,
apiEmail: argv.cloudflare && argv.cloudflare.apiEmail,
},
pinata: {
apiKey: argv.pinata && argv.pinata.apiKey,
secretApiKey: argv.pinata && argv.pinata.secretApiKey,
},
},
}
deploy(deployOptions)
} catch (e) {}
})()
Security
We use dotenv to handle credentials. Don’t commit your .env file to source
control.
Background
So far, ipfs-deploy integrates with these services:
-
Infura.io: freemium pinning service. Doesn’t require
signup. (Default.) -
Pinata.cloud: freemium pinning service. Gives more
control over what’s uploaded. You can delete, label, and add metadata. -
Cloudflare DNS: freemium DNS API. Supports CNAME
for naked domains and integrates with their IPFS gateway at
cloudflare-ipfs.com.
Feel free to request or add support to other services and send a PR.
You can start using ipfs-deploy without signing up for anything.
Default settings deploy to infura.io, which doesn’t
request an account to pin stuff. They probably do some rate-limiting, but
either way, take it easy on them. Being able to try IPFS out without friction
and without giving out personal info is a very important smooth on-ramp.
Cloudflare IPFS doesn’t host the content itself (it’s a cached gateway), so a
stable pinning service is needed if you don’t want to rely on your computer’s
IPFS daemon’s availability to serve your website.
These are free services subject to their terms. Not a decentralization nirvana
by any stretch of the imagination, but a nice way to get started quickly with a
blog, static website, or frontend web app.
If you use this package to deploy your website, please send a pull request so I
can add it to the Users section in the README. (I reserve the right
to exercise discretion.)
Contributing
PRs accepted. Please open an issue first so we can talk about it.
Small note: If editing the Readme, please conform to the
standard-readme
specification.
Users
License
BlueOak-1.0.0 OR BSD-2-Clause-Patent OR MIT © Agent of User
(The first two are the most permissive possible ever, more than MIT, which
doesn’t have a patent waiver. Use whichever satisfies your lawyer better.)
