Domain Node Setup

this page is hidden for now

Prerequisites

System Requirements

  • 2 dedicated vCPUs (must be recent, eg. 2015+ vintage from AMD/Intel)

  • 4GB RAM

  • 50GB SSD storage

  • Datacenter-quality internet connection (eg. AWS, GCP, or similar)

  • Proxy for caching, DDoS protection (eg. Nginx, Envoy, Cloudflare)

Infrastructure Requirements

  • Ability to run a container-based workload.

  • A fully qualified domain name for the node (e.g. domain-node.operator.com) with a valid SSL certificate

  • SSL termination via a load balancer or other ingress for the domain node url AND any url(s) for the applications using this domain node. The container expects to receive unencrypted traffic.

  • Operations support to enable high uptime and availability

Dependencies

  • An Ethereum account that will manage your EarthFast resources on-chain (staking, node registration, etc.).

  • An Ethereum RPC provider capable of serving 100,000 requests per day (e.g. Chainstack, Blockdaemon, Infura, Alchemy, Quicknode or your own Ethereum node).

Part 1: Domain Node Setup

Step 1: Select your Domain Name and IP address

  1. Prepare a domain for projects to point to. A easy domain and an IPv4 option make DNS easy to configure for projects.

Step 2: Configure the Domain Node

  1. The EarthFast Domain Node software is packaged as Docker container, and is hosted on GitHub's package registry where it's publicly accessible:

    https://ghcr.io/armada-network/domain-node

  2. Configuration for the container is handled exclusively via environment variables. The following values should be set in the environment when launching the container:

    Environment VariableRequiredDescription

    CONTRACT_ADDRESS

    yes

    The EarthFast smart contract address (see below).

    ETH_RPC_ENDPOINT

    yes

    Ethereum RPC endpoint URL. Sepolia is currently used for both staging and testnet.

    IP_LOOKUP_API_KEY

    yes

    API key for IP Geolocation for the Abstract API service. To obtain an API key please go to https://www.abstractapi.com/api/ip-geolocation-api

    DOMAIN_TO_PROJECT_MAPPING

    yes

    Mapping of domain to ProjectID for project(s) that use this domain node. The format is DOMAIN_TO_PROJECT_MAPPING=app.project1.com=0xaaa,app.project2.com=0xbbb,app.project3.com=0xccc

    HTTP_PORT

    yes

    Port to bind the HTTP server.

    LOG_LEVEL

    no

    Logging level: debug, info, warn, or error. Defaults to info.

EarthFast DeploymentEthereum NetworkContract Address

testnet

sepolia

0xD2362B76f79a0AbeF38E961a28E452683691890C

testnet-sepolia

sepolia

0x172CEb125F6C86B7920fD391407aca0B5F416648

  1. Run the container:

docker run \
  -e CONTRACT_ADDRESS=$CONTRACT_ADDRESS \
  -e DOMAIN_TO_PROJECT_MAPPING=$DOMAIN_TO_PROJECT_MAPPING \
  -e ETH_RPC_ENDPOINT=$ETH_RPC_ENDPOINT \
  -e HTTP_PORT=30080 \
  -e IP_LOOKUP_API_KEY=asdf \
  -p 30080:30080 \
  armadanetwork/domain-node:latest    
  • If the container boots successfully, you'll see Serving HTTP on 0.0.0.0:30080 in the logs.

  • Try hitting the server, which should output the node's status code:

curl localhost:30080 -I
  1. Connect your domain node to your DNS and any other steps to make it available on production

  2. Test your deployed domain node. Just as before, you should be able to fetch the /statusz page but this time via the real hostname:

    curl https://<your_domain_node_hostname>
  3. That's it! Projects can now connect to this domain node.

Part 2: Adding new project(s) to domain node

Before projects can start using the domain node, the domain node operator needs to add SSL termination for the project's domain. Domain nodes can serve multiple projects and can multiplex effectively between all of them. These steps will need to be run for each new project to be added.

  1. Project adds CNAME record for the application url eg CNAME app.project-url.com domain-node.operator-url.com

  2. Domain node operator adds SSL termination app.project-url.com. A simple way to do this is use LetsEncrypt + nginx to provision SSL certificates

  3. Domain node operator updates the DOMAIN_TO_PROJECT_MAPPING env var and reboots the domain node service

  4. Once SSL certification is issued, app.project-url.com should start loading

The other Project setup steps are given at https://docs.earthfast.com/host-project

Monitoring

You should monitor the container health of domain nodes that are running in production, including:

  • CPU utilization

  • Memory utilization

  • Disk utilization

  • Network utilization

Last updated