Prepare the node for deployment

Before you start a node, you must install the PostgreSQL database. For more information, see Set up PostgreSQL database.

Hardware requirements

Ensure that the node has the following minimum hardware specifications, either as physical hardware or virtual:

System node

Requirements:

• RAM: 128 GB
• vCPU: 32
• Storage: 4 TB, fast NVME SSD

To ensure that your hardware is fast enough to process data, we recommend running the Postchain Benchmark. For optimal performance, aim for 1000 ms/op for a single node and 2000-2500 ms/op for multiple nodes.

Dapp node

Requirements:

• RAM: 256 GB
• vCPU: 32
• Storage: 8 TB, fast NVME SSD

Running the Postchain Benchmark is also advisable here, with the same performance targets as for the system node.

For a mainnet Dapp node, an approximate disk space of 8 TB is necessary, split across at least two partitions or disks:

• A 2 TB partition or disk should support the Linux system, the master node, and its PostgreSQL database.
• A separate 6 TB partition or disk should accommodate the subchains and their PostgreSQL databases, with project quotas enabled on the filesystem.

Set up project quotas on /dev/vdb:

note

The following instructions may not apply to all Linux systems.

1. Create a new partition table and partition — use sudo fdisk /dev/vdb to create a new partition table and partition. Follow the prompts:

   sudo fdisk /dev/vdb
   # Press m for help
   # Press g to create a new empty GPT partition table
   # Press n to add a new partition
   # Press w to write the table to disk and exit

2. Format the partition and enable quotas — format the new partition and enable quotas with:

   sudo mkfs.ext4 -O quota -E quotatype=prjquota /dev/vdb1

3. Create the mount point and enable project quotas — create a directory with:

   mkdir -p /data/chromia/subnodes
   quotaon -P prjquota /data/chromia/subnodes

4. Configure auto-mount — add the following to /etc/fstab to ensure the system mounts it upon restart:

   /dev/vdb1 /data/chromia/subnodes ext4 prjquota 0 2

5. Mount all filesystems — execute the following to mount all filesystems specified in fstab:

   mount -a

   Consider using the UUID of the partition instead of /dev/vdb1 in /etc/fstab for increased stability.

   To verify that everything is set up correctly, run:

   mount | grep subnodes

   The expected output is:

   /dev/vdb1 on /data/chromia/subnodes type ext4 (rw,relatime,prjquota)

You can start a Chromia node as a:

• Docker container
• Native process

But first, you need a configure the node.

Node configuration

Required configuration files

• bc-config.xml

  The bc-config.xml file configures the genesis block (block height 0) and helps your node discover chains and sync them.

• node-config.system.properties

  This file defines your node’s core operations. Most fields are pre-filled, but you will need to fill in fields such as your node key pair under messaging.pubkey and messaging.privkey.

Generate a node key pair

All nodes on the network have their own unique key pair. The nodes consensus algorithm uses it to sign blocks between its peers.

To generate one key pair for each node, you start with the following:

pmc keygen --save node_keypair

Assign a static IP address

Ensure that your node machine is assigned a static IPv4 address.

Open required TCP ports

Enable incoming TCP traffic on these specific ports:

• 7740 (API port): Used for general API interactions.
• 7750 (Debug port): Enables debugging. This can be disabled post-setup.
• 9190 (Prometheus port): Collects metrics about your node’s performance.
• 9870 (Sync port): Facilitates synchronization between nodes.

Prepare Postgres credentials

Set up a Postgres password and store it securely, as it will be required during installation.

Set up a domain

You will need a domain prepared to host your node on the network.

Node setup

1. bc-config.xml: This file configures the genesis node at block height 0. It enables your node to discover existing chains and synchronize with them.

   To obtain the bc-config.xml file, you first need to locate the bird of the System Chain:

   //get the brid
   curl <system node in network api url>/brid/iid_0
   
   mainnet example
   curl https://system.chromaway.com:7740/brid/iid_0
   7E5BE539EF62E48DDA7035867E67734A70833A69D2F162C457282C319AA58AE4

   Then, retrieve the chain's config (the bride) at height 0:

   //get the config
   curl <system node in network api url>/config/<brid>?height=0 > bc-config.xml
   
   //mainnet example
   curl https://system.chromaway.com:7740/config/7E5BE539EF62E48DDA7035867E67734A70833A69D2F162C457282C319AA58AE4?height=0 > bc-config.xml

2. node-config.system.properties: This template outlines the configuration and operation of your node. Most of the property fields come pre-filled, but you must complete a few fields yourself. These are marked with either name of property or FILL IN HERE. For instance, you should specify the node_keypair file, which contains your node's keypair, under the attributes messaging.pubkey and messaging.privkey.

   Allow TCP traffic on the api and sync ports configured in the node-config.dapps.properties or node-config.system.properties file.

   note

   Note that the api port must have the TLS enabled - you can use the reverse proxy for that purpose. The sync port must be opened on the host without TLS enabled.

   Refer to the port descriptions provided above.

Configuration examples

Dapp node configuration example

# Postchain configuration file for dapp nodes in Chromia mainnet
messaging.privkey=<private key of your node -- NOT of your provider>
messaging.pubkey=<public key of your node -- NOT of your provider>
messaging.port=9870
genesis.pubkey=037434C8D4F2B7B7DE44E80486A814676DC3D898FD4488E10E1940B1C4C5837200
genesis.host=system.chromaway.com
genesis.port=9870
api.port=7740
database.driverclass=org.postgresql.Driver
database.username=postchain
database.password=<insert password here>
database.url=jdbc:postgresql://172.17.0.1:5432/postchain
database.schema=postchain0
infrastructure=net.postchain.d1.D1MasterInfrastructureFactory
container.docker-image=registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-subnode:3.16.16
container.subnode-database-url=jdbc:postgresql://localhost:5432/postchain
container.host-mount-dir=/data/chromia/subnodes
container.label.vector=postchain
container.filesystem=ext4
container.host-mount-device=<path to device, NOT partition -- e.g. /dev/nvme1n1>
container.master-port=9880
container.master-host=172.17.0.1
container.subnode-host=172.17.0.1
container.metrics.prometheus.port=9190
container.log4j-configuration-file=/node-mounted-files/log4j2.yml
api.enable_tls=false
metrics.prometheus.port=9190
configuration.provider.node=managed
container.postgres_max_locks_per_transaction=1024
database.blockBuilderWriteConcurrency=100
database.readConcurrency=100

System node configuration example

# Postchain configuration file for system nodes in Chromia mainnet
messaging.privkey=<private key of your node -- NOT of your provider>
messaging.pubkey=<public key of your node -- NOT of your provider>
messaging.port=9870
genesis.pubkey=037434C8D4F2B7B7DE44E80486A814676DC3D898FD4488E10E1940B1C4C5837200
genesis.host=system.chromaway.com
genesis.port=9870
api.port=7740
database.driverclass=org.postgresql.Driver
database.username=postchain
database.password=<insert password here>
database.url=jdbc:postgresql://172.17.0.1:5432/postchain
database.schema=postchain0
infrastructure=net.postchain.d1.D1InfrastructureFactory
api.enable_tls=false
metrics.prometheus.port=9190
configuration.provider.node=managed
container.postgres_max_locks_per_transaction=1024
database.blockBuilderWriteConcurrency=100
database.readConcurrency=100