AVN Cloud Node

Official Docker image for running AVN parachain nodes. The container runs substrate-bootstrap with bundled configuration under /opt/bootstrap/config/. The image is published as public.ecr.aws/aventus/avn-cloud-node and is built on public.ecr.aws/aventus/node-parachain using the same version tag for the base image at build time.

Prerequisites

• Docker (Install Docker Engine)
  • Ubuntu
  • Debian
  • CentOS
  • Fedora
  • RHEL
• Docker Compose V2 (included with Docker Engine)

Quick Start

services:
  avn-node:
    image: public.ecr.aws/aventus/avn-cloud-node:latest
    environment:
      - ENVIRONMENT=mainnet
      - REGISTERED_NODE_ID=0123456789abcdexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - PRIVATE_SIGNING_KEY=0x52caa9b0b5a4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    volumes:
      - ./data:/data
    ports:
      - "40333:40333"

How it works

The container runs:

substrate-bootstrap --config /opt/bootstrap/config/${ENVIRONMENT}.yml

ENVIRONMENT must be mainnet or testnet so it matches the bundled mainnet.yml or testnet.yml file.

Required configuration

Variable	Description
REGISTERED_NODE_ID	The node’s public key: 32-byte value as 64 hexadecimal characters (no 0x prefix).
PRIVATE_SIGNING_KEY	Hex-encoded private signing key used to populate the keystore (include the 0x prefix).
ENVIRONMENT	One of mainnet or testnet.

These variables are required by the bundled bootstrap configuration (bootstrap.required_env in the per-environment YAML files).

Optional configuration

Network

Variable	Description
ENVIRONMENT	Selects the bundled config file (default in image: mainnet).
CHAIN_NODE_PORT	Parachain P2P port inside the container (default: 40333). If you change it, publish the same port mapping on the host.
HOSTNAME	Optional. Used as the node name where the bundled config references ${HOSTNAME}.

Pruning

blocks_pruning and state_pruning are set in the bundled YAML per environment (for example archive-canonical for blocks and 256 for state on mainnet and testnet;). They are not controlled by separate container environment variables. To change pruning, use a custom configuration and adjust how you invoke the container, or extend or rebuild the image.

Metrics and telemetry

Telemetry endpoints are defined in the bundled config (telemetry.urls). JSON-RPC is exposed on port 9944 as set in the bundled extra_args. Substrate-based nodes typically expose Prometheus metrics on port 9615; map that port on the host if you scrape metrics.

Data directory

Mount a persistent, writable directory at /data:

• /data/keystore — Node signing keys (the bootstrap step inserts the nodk key from PRIVATE_SIGNING_KEY).
• Chain data — Databases and node files under /data according to substrate-bootstrap and the chain_data settings in the selected config (for example chain_id for parachain and relay).
• bootstrap_state.json (or similar) — May be written under /data to record bootstrap progress.

The image runs as the non-root user avn-node. The host directory must be writable by that user inside the container (for example):

chmod o+w data

volumes:
  - ./data:/data

Port configuration

Default ports:

Port	Purpose
40333	Parachain P2P (CHAIN_NODE_PORT)
9944	JSON-RPC
30333	Relay chain P2P
9615	Prometheus metrics (map when scraping)

Environment changes

When switching ENVIRONMENT (for example from mainnet to testnet):

1. Stop the container.
2. Remove or replace the data directory (do not reuse the same keystore and databases across networks).
3. Update environment variables.
4. Start the container again.

Example configurations

Basic node

services:
  avn-node:
    image: public.ecr.aws/aventus/avn-cloud-node:latest
    environment:
      - ENVIRONMENT=mainnet
      - REGISTERED_NODE_ID=0123456789abcdexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - PRIVATE_SIGNING_KEY=0x52caa9b0b5a4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    volumes:
      - ./data:/data
    ports:
      - "40333:40333"

Testnet node with RPC, relay P2P, and metrics

services:
  avn-node:
    image: public.ecr.aws/aventus/avn-cloud-node:latest
    environment:
      - ENVIRONMENT=testnet
      - REGISTERED_NODE_ID=0123456789abcdexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - PRIVATE_SIGNING_KEY=0x52caa9b0b5a4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    volumes:
      - ./data:/data
    ports:
      - "40333:40333"
      - "9944:9944"
      - "30333:30333"
      - "9615:9615"

Custom parachain P2P port

services:
  avn-node:
    image: public.ecr.aws/aventus/avn-cloud-node:latest
    environment:
      - ENVIRONMENT=mainnet
      - CHAIN_NODE_PORT=40334
      - REGISTERED_NODE_ID=0123456789abcdexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      - PRIVATE_SIGNING_KEY=0x52caa9b0b5a4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    volumes:
      - ./data:/data
    ports:
      - "40334:40334"

Security

Do not commit real PRIVATE_SIGNING_KEY values to version control. Use Docker secrets or your orchestrator’s secret management in production. For local Compose, copy docker-compose.example.yml to docker-compose.yml, fill in your values, and keep docker-compose.yml untracked (it is listed in .gitignore).

Version tags

Use specific version tags for production deployments (for example public.ecr.aws/aventus/avn-cloud-node:v1.0.0). The tag should match the node-parachain base image version used when that image was built. The latest tag points to the most recent published build from CI.