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:

   Environment Variable	Required	Description
   CONTRACT_ADDRESS	yes	The Armada 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.

Armada Deployment	Ethereum Network	Contract Address
testnet	sepolia	0xD2362B76f79a0AbeF38E961a28E452683691890C
testnet-sepolia	sepolia	0x172CEb125F6C86B7920fD391407aca0B5F416648

3. 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

4. Connect your domain node to your DNS and any other steps to make it available on production

5. 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>

6. 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