OE Node installation and configuration

Prerequisites

Hardware requirements

The minimum hardware requirements for the server that will run the OE Node are:

  • number of cores: 2

  • RAM: 16 GB

  • disk: 50 GB

Software requirements

  • Operating System: Any Linux distribution supported by the Docker Engine and Docker Compose products. For guidance on compatible platforms, see the Docker Compose supported platforms and Docker Engine supported platforms documentation

  • For OE Node v3.0.1 and newer: A Linux distribution with library glibc v2.38 or newer. To check the current version of glibc, run the following command:

ldd --version
  • Software products:

    • Docker Engine

    • Docker Compose

Other requirements

  • Blockchain RPC provider: Use a service such as Alchemy, Infura, or Chainstack. Ensure that your subscription tier supports a sufficient number of requests per second to meet the node demand.

  • IPFS gateway provider: Use a gateway such as Pinata, Cloudflare, or Filebase. Verify that your subscription tier provides adequate storage capacity, file limits, and request throughput for your expected workload. Note: Make sure the IPFS gateway used by the OE Node is a public gateway so the node can retrieve the CIDs that were pinned during asset publishing.

Pre-installation steps

Make sure you review the Compatibility Matrix to ensure that the version is compatible with the other components.

Deployment steps

The OE Node uses Elasticsearch as the underlying database for its indexer. Elasticsearch can be deployed together with the OE Node or installed separately.

There are multiple ways to install and run the OE Node, but this guide focuses on two primary approaches: using Docker Compose or PM2.

Use Docker Compose to install and run OE Node

To install and configure the OE Node using Docker Compose, perform the following steps:

  1. The OE Node repository is located here. Clone the OE Node repository.

  1. Copy .env.elasticsearch.example to .env.elasticsearch

  1. Edit the .env.elasticsearch file and set the ELASTIC_PASSWORD parameter to the password required to connect to the ElasticSearch instance.

  1. Copy .env.node.example to .env.node

  1. Edit the .env.node file and set the OE Node environment variables according to your configuration (see the Environment Variables chapter for details on how to set them).

Note: Make sure the password set in the DB_PASSWORD parameter matches the password configured for the Elasticsearch instance in step 4.

  1. Start the services

On the first run, the script creates both the Elasticsearch and OE Node containers. Because the OE Node depends on Elasticsearch reaching a specific ready state, it may take some time before the OE Node container starts.

Note: This installs the latest available version of the OE Node. To install a specific version, edit the docker-compose.yml file and set the desired version tag.

Use PM2 to run the OE Node

In this configuration, the OE Node runs as a process on the host machine, and it's managed by pm2.

Preinstallation tasks:

  1. Make sure you have the following tools installed on your Linux system:

  • node.js: the required version of node.js is listed in the .nvmrc file in the OE Node repository. Make sure this is the default version. To this end, you can use the nvm tool.

  • pm2. Optionally, you can install pm2-logrotate to easily manage the OE node logs.

  1. Start Elasticsearch in a Docker container on the host machine:

To install and run the OE Node using pm2, perform the following steps:

  1. The OE Node repository is located here. Clone the OE Node repository.

  1. Copy .env.example to .env

  1. Edit the .env file to set the environment variables specific to your configuration (please refer to the Environment Variables chapter for how to set the variables).

  1. Load the environment variables in the current session

  1. Start OE Node process in pm2

  1. Once the process is started, verify its state.

  1. Verify the logs to make sure the node started well

Post installation steps

  • If the OE Node is not configured to use HTTPS directly, deploy it behind a reverse proxy responsible for TLS termination and secure request forwarding. The proxy should enforce HTTPS for all external traffic and route decrypted requests to the OE Node's internal port.

  • Ensure that the OE Node operates in a network environment that permits outbound communication to the configured Policy Server, Policy Server Proxy, and Marketplace

  • For OE Nodes that provide a paid C2D environment, verify that the associated web3 address maintains sufficient native‑token funds on the connected blockchain to cover gas fees for withdrawals from the escrow account. Monitor and replenish the OE Node’s balance regularly.

Environment variables

In this chapter, the key environment variables required to configure the OE Node are highlighted. The full list of available environment variables is provided in the documentation for the Community Edition of the node, accessible here.

Private Key

PRIVATE_KEY

Description: Sets the private key used by the OE Node to encrypt and decrypt assets.

Values: String

Example: "0x1d751ded5a32226054cd2e71261039b65afb9ee1c746d055dd699b1150a5befc"

Default Value: null

Blockchain RPC

RPCS

Description: Sets the list of blockchains, by blockchain ID (e.g., 1 - Ethereum, 11155111 - Eth Sepolia), to which the OE Node connects to retrieve assets. If not specified otherwise in the INDEXER_NETWORKS variable, the indexer will connect to all the blockchains listed here.

Also, for each blockchain, two things are specified:

  • "rpc" : The RPC provider URL. Use the RPC URL supplied by the RPC provider.

  • "startBlock" : The block number from which the indexer will search for events related to the asset creation or update. Verify the

Values: JSON map of chainId to object

Example: {"11155111":{"rpc":"https://eth-sepolia.g.alchemy.com/<your_key>","chainId":11155111,"network":"sepolia","chunkSize":50,"startB lock":9802079},"11155420":{"rpc":"https://opt-sepolia.g.alchemy.com/<your_key>","chainId":11155420,"network":"optimism_sepolia","chunkSize": 50,"startBlock":36735314}}

Default Value: {}

Decentralized File Systems

IPFS_GATEWAY

Description: Sets the URL of the IPFS gateway used to fetch the asset's DDO. Use the URL supplied by the IFPS provider. Make sure the IPFS gateway is public; otherwise will not be able to access CIDs pinned by other services, such as the marketplace.

Values: String (URL)

Example: https://ipfs.io/

Default Value: null

Elasticsearch connection

DB_URL

Description: Sets the URL for connecting to the Elasticsearch instance.

Values: String (URL)

Example: http://elastic:<your_elasticsearch_password>@localhost:9200/ (if Elasticsearch is deployed on the same hostmachine as OE Node)

Default Value: null

DB_USERNAME

Description: Sets the user name for connecting to the Elasticsearch instance.

Values: String

Example: "elastic"

Default Value: null

DB_PASSWORD

Description: Sets the password for connecting to the Elasticsearch instance. Make sure you use the same password you set when you started the Elasticsearch container.

Values: String

Example: "elastic"

Default Value: null

Node fees

FEE_TOKENS

Description: Sets the tokens used for the node fees for each blockchain the OE Node is connected to.

Values: JSON array of string (chainId) to string (token address) mapping

Example: {"11155111":"0x1B083D8584dd3e6Ff37d04a6e7e82b5F622f3985","11155420":"0xf26c6C93f9f1d725e149d95f8E7B2334a406aD10"}

Default Value: null

FEE_AMOUNT

Description: Sets the absolute value of the fee and the unit to which the fee is applied. However, applying the fee per unit is currently not implemented in OE Node, so the fee is applied when an asset is purchased, regardless of its size.

Values: JSON object

Example: {"amount":1,"unit":"MB"}

Default Value: null

Policy Server

POLICY_SERVER_URL

Description: Sets the URL of the Policy Server used by the OE Node to perform the verification (address-based and SII-based) on asset access attempts. If no URL is set, then SSI verification is disabled and the OE Node performs only address-based verification.

Values: String (URL)

Example: "https://ps3.demo.oceanenterprise.io/"

Default Value: null

POLICY_SERVER_API_KEY

Description: Sets the API KEY used by Policy Server to authenticate API requests. Set the same key that was used in the POLICY_SERVER_API_KEY variable of the corresponding Policy Server. If API requests authentication is not enabled on the Policy Server side, leave this variable null.

Values: string

Example: mrgcorhTzA1Ey2WRhZAK8tkw4zBrIgQ757toUz3fXvfHh8Ua

Defaul Value: null

Compute Environment

DOCKER_COMPUTE_ENVIRONMENT

Description: Sets the Docker-based compute environment of the OE Node.

Value: JSON list of objects

Example:

  • For OE Node up to v2.1.1

Here's the structured format of the same value.

The configuration described by this value provides free and paid compute environments. The free compute environment has a maximum job duration of 30 minutes, a maximum number of 3 simultaneous jobs, and limited resources (1 CPU, 1 GPU, 0.5GB of RAM, and 0.5GB of disk). The paid environment has more resources to allocate and allows a maximum job duration of 60 minutes.

  • For OE Node v3.0.1 or newer

Here's the structured format of the same value.

The configuration described by this value provides two different environments on the same host: environment 1 and environment 2. Each environment has two sub-environments: paid and free. For each environment, the available resources are listed, as well as the price of each resource, for each blockchain to which the node is connected.

For details on how to set this variable, refer to the information available here.

If you want the C2D environment to provide GPU resources, please refer to this guide on how to set it up.

Default Value: null (i.e., no C2D environment provided by the node).

OE Node Ownership

NODE_OWNER_INFO

DOCKER_COMPUTE_ENVIRONMENT

Description: Sets information about the owner of the OE Node

Value: JSON object.

Example: The recommended structure of this field is provided in the example below.

Default Value: null

Last updated