Project Setup

Host your website on EarthFast

EarthFast is currently in Testnet, and its Smart Contracts live on Sepolia Testnet

For most projects, the no-code Dashboard is the simplest and quickest way to get setup. Continue to the docs below if you want a more involved, custom setup

Prerequisites

• Your website

  • Must contain an index.html entrypoint

  • all rendering/logic should be run in browser (ie. no server-side rendering)

  • Supports client-side frameworks like React, Vue, Svelte, etc., and static site generators like Gatsby

  • If using Next.js, follow static export docs

• A subdomain on which your site will be hosted

• Access permissions – if your site makes API calls to backend or API services (eg. Infura, Alchemy), ensure your new EarthFast subdomain is added to any CORS policies or domain allowlists

Ethereum

• An Ethereum wallet (OwnerWallet) to manage EarthFast resources on-chain

• ETH for tx execution. For Testnet, use Sepolia ETH

• USDC for paying Content Nodes. for Testnet, we will fund your OwnerWallet with Sepolia USDC

Step 1 – Setup EarthFast CLI

https://github.com/earthfast/earthfast-cli – You will use this CLI to manage all EarthFast resources.

Below commands instruct you to use this cli via npx, which means you don't have to install anything.

For all available commands and options run npx earthfast-cli --help. For help on individual commands append --help to a command, eg. npx earthfast-cli project create --help.

Where to run CLI

This is intended to run in your dev environment, not your node VM, although you can run it wherever you like. Currently supported on MacOS + Debian.

If running on Debian, install deps

> sudo apt-get install libsecret-1-dev gnome-keyring dbus-x11

[Optional] Alias

For brevity, consider setting up a shell alias like alias ef="npx earthfast-cli"

Decide how you will sign Eth transactions

The CLI can sign transactions for you if you import your wallet into its keystore. This is done locally using keytar – you can see the code here.

> npx earthfast-cli key import

Alternatively, you can set the optional signer flag to --signer=ledger for use with a Ledger, or --signer=raw to export transaction info for external signing.

Step 2 – Setup your project onchain

Prequisites – OwnerWallet must hold sufficient ETH to execute tx, and sufficient USDC to pay for hosting. For Testnet, use Sepolia ETH & USDC

Create the project

> npx earthfast-cli project create project-name contact-email

If successful, you should see the below output. Save your projectId for later.

> npx earthfast-cli project create ProjectName [e-mail]

...
- Submitting transaction... done
> https://sepolia.etherscan.io/tx/0x...
- Processing transaction... done
[
  {
    event: 'ProjectCreated',
    args: {
      projectId: '0x...',
      owner: 'OwnerWallet',
      name: 'ProjectName',
      email: '[e-mail]',
      content: '',
      checksum: '0x0000000000000000000000000000000000000000000000000000000000000000',
      metadata: ''
    }
  }
]

Deposit escrow

Deposit some USDC into your project's escrow. These tokens will be used to pay Content Nodes for hosting your project site.

> npx earthfast-cli project deposit ProjectId 100.0

If successful, you should see the below output.

> npx earthfast-cli project deposit projectId 100.0

...
- Requesting signature... done
- Submitting transaction... done
> https://sepolia.etherscan.io/tx/0x...
- Processing transaction... done
[
  [
    {
      event: 'ProjectEscrowChanged',
      args: {
        projectId: 'projectId',
        oldEscrow: 'BigNumber 0 / 0.0 / 0.0',
        newEscrow: 'BigNumber 100000000 / 100.0 / 0.0000000001'
      }
    }
  ]
]

Make a reservation with a Content Node

Find an available Content Node:

> npx earthfast-cli node list --enabled --vacant

# --vacant = lists nodes available in the current and next epoch
# To see all available flags, run:
> npx earthfast-cli node list --help

Using node IDs returned from above (the value for id key), make your reservation. See npx earthfast-cli reservation create --help to set the flags per your preferences.

> npx earthfast-cli reservation create --spot --renew projectId nodeId

# or reserve multiple nodes at once by passing a comma separated list of nodeIDs
> npx earthfast-cli reservation create --spot --renew projectId nodeId1,nodeId2,nodeId3

If successful, you should see the below output.

> npx earthfast-cli reservation create --spot --renew projectId nodeId

...
- Submitting transaction... done
> https://sepolia.etherscan.io/tx/0x...
- Processing transaction... done
[
  {
    event: 'ReservationCreated',
    args: {
      nodeId: '0x...',
      operatorId: '0x...',
      projectId: '0x...',
      lastPrice: 'BigNumber 1000000 / 1.0 / 0.000000000001',
      nextPrice: 'BigNumber 0 / 0.0 / 0.0',
      slot: [ true, true ]
    }
  }
]

Step 3: Bundle your site assets

Option 1: via GitHub Actions (recommended)

If your project is hosted on GitHub, this option greatly simplifies the integration by taking care of both (1) bundling the site into an EarthFast-compatible artifact and (2) leveraging the binary asset serving capability of GitHub Releases to host that artifact.

The GitHub Action itself can be found at github.com/earthfast/armada-release-action, or you can follow the demo project at github.com/earthfast/demo-project for a complete example.

Option 2: Manual

Building the Site

EarthFast is designed to be able to be easily integrated into your existing build pipeline. With the help of the CLI, you will package your site’s production build into an artifact that can be served by the network (i.e. the “EarthFast bundle”).

1. Build your site as you normally would into a final output directory (i.e. dist, build, etc.).

2. Create the EarthFast bundle by running the following command, replacing the placeholders with appropriate values (archive-name-and-version can be anything you want, build-dir should be the directory from Step 2: Signing Up above):

> npx earthfast-cli bundle create <archive-name-and-version> <build-dir>

# Example:
> npx earthfast-cli bundle create my-site-v1.0.1 ./dist

1. The previous command will print the final bundle filename, which you’ll need now. Run the following to obtain the checksum of the bundle, which you’ll need later:

> npx earthfast-cli bundle checksum <bundle-filename>

# Example:
> npx earthfast-cli bundle checksum my-site-v1.0.1.tgz

Hosting the bundle

Once your site has been bundled for use on EarthFast, it needs to be published somewhere on the Internet where it’s:

1. Publicly accessible

2. Will remain available as long as it’s the live version

Both of the above are necessary because the nodes that operate the EarthFast network will fetch your site from this location throughout their serving lifetimes. However, the content is heavily cached so the request rate for the bundle should be extremely low.

Suggested locations for hosting your bundle:

• GitHub Release Assets

• AWS S3 / Google Cloud Storage / Azure Blob

Not recommended locations that would still work:

• IPFS – you’ll need to pin the file, fetching performance will likely be poor, and you’ll need to use an IPFS gateway to get a publicly accessible URL.

Step 4: Publish Bundle to EarthFast

Now that your bundle is hosted publicly, you need to publish it to instruct your newly reserved Content Nodes to begin serving your site.

> npx earthfast-cli project publish <project-id> <bundle-url> <bundle-checksum>

If successful, you should be able to curl this url and get a 200 JSON response: https://<node-url>?project_id=<project-id>&resource=earthfast.json

Custom Domain

Your project is now live on the EarthFast network, but you most likely want to set up a custom domain.

Option 1 – [Coming Soon] Use EarthFast's Domain Node as a Service

Option 2 – Set up a serverless domain node

Follow the instructions on this repo to get setup – https://github.com/earthfast/earthfast.com-on-earthfast