Content Node Setup

Prerequisites

System Requirements

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

• 4GB RAM

• 100GB 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 each node (e.g. content4.us-east-2.operator.com) with a valid SSL certficate. Wildcard certificates are allowed.

• SSL termination via a load balancer or other ingress. The container expects to receive unencrypted traffic.

• Operations support to enable high uptime and availability.

Other Prerequisites

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

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

Setup

Step 1: Prepare your Account & Getting your OperatorID

1. Registering nodes on the Armada testnet is only possible for Ethereum accounts that have been explicitly granted permission to do so. Send the Ethereum account (public key) that you want to be whitelisted to a member of the Armada team. After approval, you will be given a unique OperatorID that's associated with your Ethereum account. You'll use this OperatorID later to register and adminster your nodes.

Step 2: Choose your Domain Names

1. Each individual Armada Content Node must be addressable by a unique fully qualified domain name. Decide what top-level domain you will use, and choose a naming convention for individual nodes. Since you will likely be running multiple nodes in multiple regions, we recommend something like content<N>.<location>.<network>.armada.operator.com. Network can either be testnet-sepolia or mainnet. Location can be region code from Step 3, cloud provider regions eg us-east-1, na, us or something similar. Following this pattern, some domain names might be:

   • content0.us-east-2.testnet-sepolia.armada.operator.com

   • content12.eu.testnet-sepolia.armada.operator.com

   • content3.usw2.testnet-sepolia.armada.operator.com

2. Be prepared to serve HTTPS traffic at these hostnames, provisioning SSL certificates as necessary.

Step 3: Identify your Region Code

Note - this region code may different from the location used in the domain name above.

1. The Armada network has the concept of regions, similar to datacenter regions. However, they are currently much more geographically coarse than is typical of datacenter regions. Use the table below to determine which Armada region code each of your nodes belongs to (you'll need this information later).

   Datacenter Continent	Armada Region Code
   Africa	af
   Asia	as
   Australia	au
   Europe	eu
   North America	na
   South America	sa

Step 4: Register your Nodes

Each Armada Content Node will have a unique NodeID on the network. This NodeID must be provided as configuration to the content node container at boot time. Therefore, the nodes must be registered before they can be booted (to obtain their NodeIDs). The nodes will be disabled upon registration, preventing them from receiving traffic until they're ready to serve. Once they're ready to serve traffic, there will be a transaction later to mark them as ready on chain.

1. Authenticate the Armada CLI using the private key for the Ethereum account provided to Armada:

   npx armada-cli key import

2. Stake the appropriate ARMADA testnet access tokens from your wallet. On testnet the default is 100 tokens per node.

   npx armada-cli operator stake <OperatorId> 100

3. Register a single node using the appropriate region code (from Step 3 above), that's disabled and has an initial price of 1.0:

   npx armada-cli node create <OperatorId> <hostname>:<region-code>:false:1.0

   Note: Run npx armada-cli node create --help for more details and examples

4. If the transaction is successful, your new node's NodeID will be logged. Save this for when you'll configure and deploy the container.

5. Repeat steps 3/4 for your other nodes or defer doing so until you have this first node fully up and running. Note that the node create command also accepts multiple, comma-separated node declarations to reduce the number of calls you need to make.

Step 5: Configure & run the Content Node container

1. The Armada Content 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/content-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).
   DATABASE_DIR	yes	Filesystem location on persistent storage where the node's database will be kept.
   ETH_RPC_ENDPOINT	yes	Ethereum RPC endpoint URL. Sepolia is currently used for both staging and testnet.
   HOSTING_CACHE_DIR	yes	Filesystem location where hosted website content will be stored. May be persistent or ephemeral as long as there is sufficient storage space (>= 20GB).
   HTTP_PORT	yes	Port to bind the HTTP server.
   LOG_LEVEL	no	Logging level: debug, info, warn, or error. Defaults to info.
   NODE_ID	yes	This node's NodeID.

Armada Deployment	Ethereum Network	Contract Address	Used For
testnet-sepolia-staging	sepolia	0xD2362B76f79a0AbeF38E961a28E452683691890C	Used for development and testing. Not for running project sites
testnet-sepolia	sepolia	0x172CEb125F6C86B7920fD391407aca0B5F416648	Used for project sites

3. Try running the container locally using your real NodeID:

export NODE_ID=<your_node_id>
docker run \
  -e CONTRACT_ADDRESS=0xF3306c86a06F542876B74BD6764E9D83bc689A9A \
  -e DATABASE_DIR=/tmp \
  -e ETH_RPC_ENDPOINT=https://rpc.ankr.com/eth_sepolia \
  -e HOSTING_CACHE_DIR=/tmp \
  -e HTTP_PORT=30080 \
  -e NODE_ID=$NODE_ID \
  -p 30080:30080 \
  armadanetwork/content-node:latest    

• If the container boots successfully, you'll see Serving HTTP on 0.0.0.0:30080 in the logs.

• Try fetching the /statusz page, which will output the node's basic status:

curl http://localhost:30080/statusz

4. Deploy the container in your production environment, ensuring that you:

   1. Pin the container image version (i.e. don't use the latest tag).

   2. Set DATABASE_DIR and HOSTING_CACHE_DIR appropriately based on your persistent disk mount configuration.

   3. Use a non-public ETH_RPC_ENDPOINT to avoid getting rate limited.

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

   curl https://<your_content_node_hostname>/statusz

Step 7: Enable your Node(s)

1. Once the node has been deployed and tested, it needs to be enabled on-chain before a project can reserve it:

   npx armada-cli node enable <node_ids> true

Monitoring

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

• CPU utilization

• Memory utilization

• Disk utilization

• Network utilization

Additionally, the content node exposes a /metrics endpoint that exports internal metrics in Prometheus format. These include, for instance, HTTP request latency distributions. The endpoint is exposed on HTTP_PORT, and is therefore publicly accessible - this is intentional as projects themselves should be able to monitor the performance of their reserved content node fleet.