Skip to main content

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>

# Postchain configuration
# Infrastructure to use. Can be net.postchain.managed.Chromia0InfrastructureFactory if all blockchains should be in the same process

# Storage
# 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.

# Node information to connect to an existing network
genesis.pubkey=<node public key><genesis address>

# Container
# Path to image used by subnode containers<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
# The host device that the `` 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
# 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
# on linux/Windows. Can be localhost if master node is a native java process
# Port used by the master node to establish connections with subnodes
# Hostname of subnodes as seen by the master host. See above
# Subnodes will spawn and host its own database, use this if you want all subnodes to use another external database

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.


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 POSTCHAIN_CONFIG=/config/ \
-e POSTCHAIN_BLOCKCHAIN_CONFIG=/build/bc-config.xml \
-p 9870:9870/tcp \
-p 7740:7740/tcp \
-p 9880:9880/tcp \<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"
$ run-node -nc config/ --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 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:


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 POSTCHAIN_CONFIG=/config/ \
-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 \<version> \

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 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:


In this case, and container.master-mount-dir(if present) , and all container files are available in /${zfs_pool_name}/${container_name}.


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-opt fluentd-address=fluentdhost:24224
--log-opt fluentd-async=true


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