# Start a node · Chromia Docs (concept)

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

Source: https://docs.chromia.com/ecosystem/providers/nodes/start-a-node/

# Start a node

On this page

* [Verify node status](#verify-node-status)
* [Start a node as a native background process](#start-a-node-as-a-native-background-process)
* [Enforce subnode disk quotas](#enforce-subnode-disk-quotas)
* [Transport Layer Security (TLS)](#transport-layer-security-tls)
* [Logging](#logging)
* [Prometheus](#prometheus)
* [Generic logs](#generic-logs)

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

Terminal

```
# 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
```

Terminal

```
# Configuration options set by default in PostgreSQL's Docker image
listen_addresses = '*'
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_connections = 200
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
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/
shared_buffers = 16GB
effective_cache_size = 32GB
maintenance_work_mem = 8GB
work_mem = 83880kB
min_wal_size = 8GB
max_wal_size = 21GB
```

3. Start the Postgres docker container:

Terminal

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

Terminal

```
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.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.

4. 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`.

Terminal

```
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.25.4 \
  run-node
```

Terminal

```
docker run \
  --detach \
  --name postchain \
  --restart unless-stopped \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --mount type=bind,source="/etc/passwd",target=/etc/passwd,readonly \
  --mount type=bind,source=/data/chromia/subnodes,target=/data/chromia/subnodes \
  --mount type=bind,source="/data/chromia/node/node-mounted-files",target=/node-mounted-files,readonly \
  -e JAVA_TOOL_OPTIONS="-Xmx192g" \
  -e POSTCHAIN_DEBUG=true \
  -e POSTCHAIN_CONFIG=/node-mounted-files/node-config-dapp.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 9880:9880/tcp \
  -p 9190:9190/tcp \
  --privileged \
  registry.gitlab.com/chromaway/postchain-chromia/chromaway/chromia-server:3.25.4 \
  run-node
```

warning

Apple M4 CPUs may need SVE to be disabled for a successful startup. If you encounter issues, try using this command
instead of the one above: `-e JAVA_TOOL_OPTIONS="-Xmx2g -XX:UseSVE=0"`

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:

Terminal

```
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`.

Terminal

```
telnet <your host> 9870
curl https://<your host>:443/version
```

note

Using port 443 for the API endpoint is recommended as it's the standard HTTPS port. You can also use port 7740 as an alternative if needed.

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

Terminal

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

Terminal

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

Properties

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

Start the master node container:

Terminal

```
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](https://docs.chromia.com/ecosystem/providers/nodes/setup-tls/).

## Logging

### Prometheus

To enable Prometheus, add `metrics.prometheus.port=<port>` to the `node-config.properties` file. For more information,
see [Set up Prometheus monitoring](https://docs.chromia.com/ecosystem/providers/nodes/setup-prometheus/).

### 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](https://docs.docker.com/config/containers/logging/configure/) 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:

Terminal

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

Properties

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

[View this page on docs.chromia.com](https://docs.chromia.com/ecosystem/providers/nodes/start-a-node/)Content mirrored from the live docs
