Domain Node Setup

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 Armada 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 Armada 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:

  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 \
  ghcr.io/armada-network/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.armadanetwork.com/armada-network-docs/host-a-project-on-armada

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