Start a node
Before you start a node, you must install the PostgreSQL database. For more information, see Set up PostgreSQL database.
You can start a Chromia node as a:
But first, you need a node configuration file as follows:
# Node configuration
messaging.privkey=<node private key>
messaging.pubkey=<node public key>
messaging.port=9870
api.port=7740
# Postchain configuration
configuration.provider.node=managed
# Infrastructure to use. Can be net.postchain.managed.Chromia0InfrastructureFactory if all blockchains should be in the same process
infrastructure=net.postchain.managed.Chromia0MasterInfrastructureFactory
# Storage
database.username=<postgres-user>
database.password=<postgres-pw>
database.schema=<postgres-schema>
# Url to database. the host must point in respect to the nodes network.
# If node is run as a Docker container, and the db is also on Docker, then this would be the internal Docker host.
database.url=jdbc:postgresql://localhost:5432/<db-name>
# Node information to connect to an existing network
genesis.pubkey=<node public key>
genesis.host=<genesis address>
genesis.port=9870
# Container
# Path to image used by subnode containers
container.docker-image=registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-subnode:<version>
# Mount path to a directory on the host that can be used to store configurations. Note that we don't want to use /tmp since this folder will be cleaned when a container is stopped
container.host-mount-dir=/var/lib/chromaway/postchain/subnode
# The host device that the `container.host-mount-dir` is located on. This is used to enforce disk I/O limits.
# Note that this should only be the name of the device, not the partition.
# For mac you may use `/dev/vda` to enforce limits
container.host-mount-device=/dev/sda
# Hostname of the master host as seen by a subnode. If master is on Docker, then the subnode will perceive the host as the internal Docker host
# 172.17.0.1 on linux/Windows. Can be localhost if master node is a native java process
container.master-host=host.docker.internal
# Port used by the master node to establish connections with subnodes
container.master-port=9880
# Hostname of subnodes as seen by the master host. See above
container.subnode-host=host.docker.internal
# Subnodes will spawn and host its own database, use this if you want all subnodes to use another external database
container.subnode-database-url=jdbc:postgresql://localhost:5432/postchain
Start a node using Docker
When starting a node using Docker, you must expose a few ports and add mount points. Folders containing node configuration, blockchain configuration, and the subnode mount path must be mounted, and the Docker socket must be a volume. The subnode mount path must have write access, and the others can be read-only. Furthermore, the messaging, API and subnode ports must be exposed. The container runs as the current user/group, and subnode containers run as the same user/group. It needs the docker group to talk to the Docker daemon.
You should also ensure that your machine doesn't run out of memory. Consider how much-dedicated memory you have left after subtracting the memory that's dedicated to dapp-containers. Also, consider the memory consumption of PostgreSQL (and any other applications you may have running on your machine). You can limit memory usage by setting JVM flags via JAVA_TOOL_OPTIONS environment variables.
Example:
docker run -d --name postchain \
--restart unless-stopped \
--user $(id -u):$(id -g) \
--group-add $(cut -d: -f3 < <(getent group docker)) \
--volume /var/run/docker.sock:/var/run/docker.sock \
--mount type=bind,source="/etc/passwd",target=/etc/passwd,readonly \
--mount type=bind,source=/var/lib/chromaway/postchain/subnode,target=/var/lib/chromaway/postchain/subnode \
--mount type=bind,source="$(pwd)/config",target=/config,readonly \
--mount type=bind,source="$(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 \
-p 9870:9870/tcp \
-p 7740:7740/tcp \
-p 9880:9880/tcp \
registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-server:<version> \
run-node
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 or ZFS. ext4 is a widely used file system for Linux operating systems that supports disk quotas. ext4 quota provides a useful tool for managing disk space usage on Linux systems. ZFS quotas are used to limit the amount of disk space a specific ZFS filesystem can use from the ZFS pool.
ext4
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="$(pwd)/config",target=/config,readonly \
--mount type=bind,source="$(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 9870:9870/tcp \
-p 7740:7740/tcp \
-p 9880:9880/tcp \
registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-server:<version> \
run-node
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.
ZFS
ZFS disk quotas require a native master node. To enable this:
Create ZFS pool named psvol:
zpool create psvol /dev/...
Add the following properties to the node configuration file:
container.filesystem=zfs
container.zfs.pool-name=psvol
In this case, container.host-mount-dir and container.master-mount-dir(if present) , and all container files are available in /${zfs_pool_name}/${container_name}.
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