Skip to main content

Start a node

To start a node, you need to complete a few prerequisites.

  1. Install the Docker on the host.

  2. Save the following configuration to /data/chromia/database/postgres.system.conf:

# Configuration options set by default in PostgreSQL's Docker image
listen_addresses = '*'
max_connections = 100
shared_buffers = 128MB
dynamic_shared_memory_type = posix
max_wal_size = 1GB
min_wal_size = 80MB
log_timezone = 'Etc/UTC'
datestyle = 'iso, mdy'
timezone = 'Etc/UTC'
lc_messages = 'en_US.utf8'
lc_monetary = 'en_US.utf8'
lc_numeric = 'en_US.utf8'
lc_time = 'en_US.utf8'
default_text_search_config = 'pg_catalog.english'
max_worker_processes = 8
max_parallel_workers_per_gather = 4
max_parallel_workers = 8
max_parallel_maintenance_workers = 4
max_locks_per_transaction = 1024

# Slow query log
log_min_duration_statement = 1s
log_parameter_max_length = 1024
log_parameter_max_length_on_error = 1024

# Tuning, inspired by https://pgtune.leopard.in.ua/
max_connections = 200
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
  1. Start the Postgres docker container:
docker run \
  --detach \
  --name postgres \
  --mount type=bind,source=/data/chromia/database/postgres,target=/var/lib/postgresql/data \
  --mount type=bind,source=/data/chromia/database/postgres.system.conf,target=/postgres.conf \
  -e POSTGRES_INITDB_ARGS="--lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --encoding=UTF-8" \
  -e POSTGRES_USER=postchain \
  -e POSTGRES_PASSWORD=<insert password here> \
  -p 172.17.0.1:5432:5432 \
  postgres:16.3 -c config_file=/postgres.conf
note

Use en_US.UTF-8 instead of C.UTF-8 if you are using Docker on Mac.

  1. Start the Postchain node.

Place all distributed files (such as log4j2.yml, node-config.system.properties, and bc-config.xml) in a single folder named /data/chromia/node/node-mounted-files on the host machine. This folder allows the Docker process to read the files.

Before starting the node, execute a docker pull for the image registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-subnode:3.16.16.

note

The Postchain server version must match the System node or Dapp node version. For example, if the Postchain server is 3.16.16, then the System node version must also be 3.16.16.

docker run \
  --detach \
  --name postchain \
  --restart unless-stopped \
  --mount type=bind,source=/data/chromia/node/node-mounted-files,target=/node-mounted-files,readonly \
  -e JAVA_TOOL_OPTIONS="-Xmx96g" \
  -e POSTCHAIN_DEBUG=true \
  -e POSTCHAIN_CONFIG=/node-mounted-files/node-config.system.properties \
  -e POSTCHAIN_BLOCKCHAIN_CONFIG=/node-mounted-files/bc-config.xml \
  -p 9870:9870/tcp \
  -p 127.0.0.1:7741:7740/tcp \
  -p 127.0.0.1:7751:7750/tcp \
  -p 9190:9190/tcp \
  registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-server:3.16.16 \
  run-node

After completing these steps, your node should be up and running!

Verify node status​

To confirm that the node has been turned on successfully, you can use the following command to curl the debug endpoint and check if the chains are starting to sync:

curl http://127.0.0.1:7751/_debug

If you call this command after a few minutes, you should see that the block height has increased.

Additionally, you can verify if the ports are configured correctly by attempting to access the node from outside using telnet and curl.

telnet <your host> 9870
curl https://<your host>:7740/version

Start a node as a native background process​

You can start the node as a background process, like a screen. You can add JVM flags by setting the environment variable JAVA_TOOL_OPTIONS. Make sure that the process gets restarted on a crash.

$ screen -S n0
# Ctrl+a, d  (means detach)
# screen -r n0  (means reattach)

$ export JAVA_TOOL_OPTIONS="-Xmx2g"
$ postchain.sh run-node -nc config/node-config.properties --blockchain-config build/bc-config.xml --debug

Enforce subnode disk quotas​

You can enforce subnode disk quotas can by using ext4. ext4 is a widely used file system for Linux operating systems that supports disk quotas. The quota provides a useful tool for managing disk space usage on Linux systems.

Ext4 disk quotas can be used with a native master node or a master node running in a Docker container with a chromaway/chromia-server image started with --privileged and run as root. To enable this:

Create an ext4 file system with project quotas enabled and mount it with project quotas enabled:

mkfs.ext4 -v -L postchain -O quota -E quotatype=prjquota /dev/...
mount -o prjquota /dev/... /mnt/chromaway/postchain

Add the following properties to the node configuration file:

container.filesystem=ext4
container.host-mount-dir=/mnt/chromaway/postchain

Start the master node container:

docker run -d --name postchain \
    --privileged \
    --restart unless-stopped \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --mount type=bind,source=/mnt/chromaway/postchain,target=/mnt/chromaway/postchain \
    --mount type=bind,source="<path to local config. For example, $(pwd)/config>",target=/config,readonly \
    --mount type=bind,source="<path to local build. For example, $(pwd)/build>",target=/build,readonly \
    -e JAVA_TOOL_OPTIONS="-Xmx2g" \
    -e POSTCHAIN_DEBUG=true \
    -e POSTCHAIN_CONFIG=/config/node-config.properties \
    -e POSTCHAIN_BLOCKCHAIN_CONFIG=/build/bc-config.xml \
    -e POSTCHAIN_SUBNODE_USER=$(id -u):$(id -g) \
    -p <internal node communications port (9870)>:<external node communications port>/tcp \
    -p 127.0.0.1:<internal api port (7740)>:<external api port>/tcp \
    -p <9880>:<9880>/tcp \
    registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-server:<version> \
    run-node
note

The recommended port is specified in the parenthesis unless it's different in the node-configuration.properties file.

If running the master node natively, it needs to run as root and the quota tool setquota needs to be installed. You can find it in the package quota in Debian and Ubuntu.

Subnode containers must run as a non-root user, configured with node configuration property container.subnode-user or environment variable POSTCHAIN_SUBNODE_USER. The value should be <user-id>:<group-id>. Numerical user and group ids must be used.

Transport Layer Security (TLS)​

TLS must be enabled on all nodes. You can add TLS with a reverse proxy. For more information, see Set up a TLS certificate.

Logging​

Prometheus​

To enable Prometheus, add metrics.prometheus.port=<port> to the node-config.properties file. For more information, see Set up Prometheus monitoring.

Generic logs​

Docker supports different log drivers that can be used when collecting logs from a running container. For more information about available log drivers, see the official logging drivers documentation.

To start a node with a specific log driver, add log-driver and, optionally, log-opt to the docker run command when starting the node.

For example:

docker run -d --name postchain \
    ...
    --log-driver=fluentd
    --log-opt fluentd-address=fluentdhost:24224
    --log-opt fluentd-async=true
    ...

Subnodes​

Since subnodes are started automatically, the log driver and log options need to be added to the node configuration file as follows:

container.docker-log-driver=fluentd
container.docker-log-opts=fluentd-address=fluentdhost:24224;fluentd-async=true