⬆️Host a project on Armada

Prerequisites

1. A new subdomain that will be used during the testnet (e.g. some-subdomain.yourproject.com).

2. A static website that you wish to host on Armada.

3. A Goerli Ethereum account that will have administrative privileges of your project/domain on the network. This account will need a nominal amount of Goerli Eth to submit transactions.

Prepare your Backend(s)

If your backend or any service provider (i.e. Infura, Alchemy, etc.) has CORS policies or domain allow lists configured, ensure that your new subdomain has been added so any API calls from your soon-to-be Armada-hosted site will not be rejected.

Step 1: Configure your Nameservers

Note: This step is optional and leverages domain nodes that are run by the Armada team and is provided as a convenience for the testnet. It's possible to host your own domain node, instructions here.

Create the following DNS records with a relatively low TTL (i.e. 5m) for your subdomain:

Record Name	Type	Value
<subdomain>.yourproject.com	CNAME	domains.testnet-sepolia.armadanodes.com.
_acme-challenge.<subdomain>.yourproject.com	CNAME	validations.domains.testnet-sepolia.armadanodes.com.

For example, if you wanted to run Armada on app.example.io, the record names would be app.example.io and _acme-challenge.app.example.io.

Step 2: Signing Up

To whitelist your public key to register for Testnet, please send an email/message to your Armada contact (or [e-mail]) with:

1. Your project’s name.

2. The fully qualified domain name that you just configured DNS records for.

3. A Goerli Ethereum account (public key) to act as administrator for your project.

4. Public contact email (for example in case node operators need to contact you)

Before continuing, wait for confirmation that your Ethereum account has been added to the Armada allow list for testnet. You should also have received Goerli USDC tokens.

Step 3: Install the CLI

We recommend installing the Armada CLI as a dev dependency of your project so that you can pin it to a specific version:

With npm:

npm install --save-dev armada-cli

With yarn:

yarn add --dev armada-cli

Step 4: Register your project via the CLI

These steps create your project on chain for the first time and allow you to get an on-chain projectID. They also let you select content nodes to host your site's content.

1. Run the command below and follow the prompts to import a ETH wallet or connect to a wallet provider (Ledger, etc):

npx armada-cli key import

2. Create the project on chain. On testnet the Armada team needs to whitelist your wallet address and transfer you some tokens, so make sure Step 2: Signing Up above has been completed.

npx armada-cli project create "My Project" [e-mail]

3. Please send your project-id to the Armada team to verify the DNS records. Once you receive confirmation move onto Step 4.

4. Next, you’ll deposit some tokens into your project’s escrow by transferring them from your wallet address (as part of the allow-listing process, your admin account will have been airdropped some Goerli USDC tokens). These tokens will be used to pay for content nodes – the resources that will ultimately serve your site.

npx armada-cli project deposit <project-id> 100.0

5. Find a content node that's available to be reserved:

npx armada-cli node list --vacant --spot --renew --size=1

Note: the --spot flag restricts the search to nodes that are available in the current epoch, and the --renew flag further restricts the search to nodes that are also available for renewal in the next epoch. Therefore, this search will find nodes available both now and going forward.

6. Using the output of the previous command to identify the node IDs, reserve the nodes:

npx armada-cli reservation create --spot --renew <project-id> <node-1-id>

Note: the --spot flag causes the reservation to begin immediately (mid-epoch), and the --renew flag makes the reservation auto-renewing. Note: you can reserve multiple nodes with the above command by passing a comma separated list of nodes eg <node1-id>,<node-2-id>

Step 5: Preparing the Site's 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 Armada-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/armada-network/armada-release-action, or you can follow the demo project at github.com/armada-network/demo-project for a complete example.

Option 2: Manually

Building the Site

Armada 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 “Armada bundle”).

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

2. Create the Armada 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 armada-cli bundle create <archive-name-and-version> <build-dir>
# Example:
npx armada-cli bundle create my-site-v1.0.1 ./dist

3. 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 armada-cli bundle checksum <bundle-filename>
# Example:
npx armada-cli bundle checksum my-site-v1.0.1.tgz

Hosting the Bundle

Once your site has been bundled for use on Armada, 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 Armada 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 6: Publish content to Armada

To publish the bundle that you created and hosted in Preparing the Site above. This will instruct your newly reserved content nodes to begin serving your site.

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

Open a browser and visit the domain name you configured for Armada!