agentofuser/ipfs-deploy

6 years ago

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.

Install

npm install -g @agentofuser/ipfs-deploy

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

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

Table of Contents