Skip to content

Latest commit

 

History

History
338 lines (233 loc) · 8.92 KB

operations.md

File metadata and controls

338 lines (233 loc) · 8.92 KB
Raw

Operations

GRPC API

The GRPC process is a Java-based application and should be able to run on any platform that Java supports. That said, we recommend Ubuntu 22.04 be used as the base operating system as that is the only OS we've tested against.

File Layout

  • /etc/systemd/system/hedera-mirror-grpc.service - systemd service definitions
  • /usr/etc/hedera-mirror-grpc/application.yml - Configuration file
  • /usr/lib/hedera-mirror-grpc - Binaries

Starting

sudo systemctl start hedera-mirror-grpc.service

Stopping

sudo systemctl stop hedera-mirror-grpc.service

Upgrading

Download release artifact from the releases page and scp it to the target server. Then execute:

tar -xvf ./hedera-mirror-grpc-*.tgz
cd hedera-mirror-grpc-*/scripts
sudo ./deploy.sh

Monitoring

systemctl status hedera-mirror-grpc.service
sudo journalctl -fu hedera-mirror-grpc.service

Verifying

The gRPC streaming endpoint can be verified using clients that support HTTP/2. Some useful clients we've encountered include:

  • grpcurl
    • Run the following command making substitutions for topicNum, grpcContainerIP and grpcContainerPort:
grpcurl -plaintext -d '{"topicID":{"shardNum":0,"realmNum":0,"topicNum":{topicNum}},"consensusStartTime":{"seconds":0,"nanos":0},"limit":10}' {grpcContainerIP}:{grpcContainerPort} com.hedera.mirror.api.proto.ConsensusService/subscribeTopic

Importer

The Importer process is a Java-based application and should be able to run on any platform that Java supports. That said, we recommend Ubuntu 22.04 be used as the base operating system as that is the only OS we've tested against.

File Layout

  • /etc/systemd/system/hedera-mirror-importer.service - systemd service definitions
  • /usr/etc/hedera-mirror-importer/application.yml - Configuration file
  • /usr/lib/hedera-mirror-importer - Binaries

Starting

sudo systemctl start hedera-mirror-importer.service

Stopping

sudo systemctl stop hedera-mirror-importer.service

If shutdown cleanly the service will log a Shutting down..... message

Upgrading

Download release artifact from the releases page and scp it to the target server. Then execute:

tar -xvf ./hedera-mirror-importer-*.tgz
cd hedera-mirror-importer-*/scripts
sudo ./deploy.sh

Monitoring

systemctl status hedera-mirror-importer.service
sudo journalctl -fu hedera-mirror-importer.service

Historical Data Ingestion

The following resource allocation and configuration is recommended to speed up historical data ingestion. The importer should be able to ingest one month's worth of mainnet data in less than 1.5 days.

  1. Importer

  • Resource allocation

    Run the importer with 4 vCPUs and 10 GB of heap.

  • Configuration:

      hedera:
    mirror:
      importer:
        downloader:
          record:
            batchSize: 600
            frequency: 1
        parser:
          record:
            entity:
              redis:
                enabled: false
            frequency: 10
            queueCapacity: 40

    Note once the importer has caught up all data, please change the configuration to the default where applicable.

  1. PostgreSQL Database

  • Resource allocation

    Run a PostgreSQL 14 instance with at least 4 vCPUs and 16 GB memory.

  • Configuration:

    Set the following parameters. Note the unit is kilobytes.

    • max_wal_size = 8388608
    • work_mem = 262144

Monitor

The monitor is a Java-based application and should be able to run on any platform that Java supports. That said, we recommend running it as a Docker container via Docker Compose or Helm.

REST API

Initial Installation

The REST API runs on Node.js and should be able to run on any platform that Node.js supports. That said, we recommend Ubuntu 22.04 be used as the base operating system as that is the only OS we've tested against. It is also recommended to create a restapi user and execute all commands as that user.

sudo apt install nodejs npm
sudo npm install -g pm2
sudo useradd --create-home restapi
sudo mkdir -p /opt/restapi
sudo chown restapi: /opt/restapi
sudo su - restapi
cd /opt/restapi
cat > application.yml <<EOF
hedera:
  mirror:
    rest:
      db:
        host: dbhost
        password: mirror_api_pass
EOF
tar --strip-components=1 -xvf hedera-mirror-rest-v*.tgz
pm2 start pm2.json

File Layout

  • /opt/restapi - Binaries
  • /opt/restapi/application.yml - Configuration

Upgrading

Replace the VERSION below with the appropriate version:

sudo su - restapi
cd /opt/restapi
pm2 stop all
wget "https://github.com/hashgraph/hedera-mirror-node/releases/download/${VERSION}/hedera-mirror-rest-${VERSION}.tgz"
tar --strip-components=1 -xvf hedera-mirror-rest-v*.tgz
pm2 start pm2.json

Starting

To start all 10 ports (6551-6560):

pm2 start /opt/restapi/pm2.json

To manually start on a specific port:

HEDERA_MIRROR_REST_PORT=8080 pm2 start server.js

Stopping

pm2 stop all

Monitoring

pm2 monit
pm2 status
pm2 logs <port>

Verifying

The REST API endpoints can be verified either through the browser or the terminal. The following endpoints are suggestions that can be accessed from your browser. Modify the below IP's and ports if they differ from your running containers.

curl http://127.0.0.1:6551/api/v1/accounts
curl http://127.0.0.1:6551/api/v1/balances
curl http://127.0.0.1:6551/api/v1/transactions

Verify all ports:

for port in {6551..6560}; do curl -s "http://127.0.0.1:${port}/api/v1/transactions?limit=1" && echo; done

To set up live monitoring, see monitoring documentation.

Open API Spec

The REST API supports the OpenAPI (Swagger) specification v3. This provides documentation and structure for metrics

View Spec UI

We utilize the swagger-ui-express package to serve our documentation based on the OpenAPI specification. The OpenAPI specification can be viewed at

  • /api/v1/docs - API v1 doc serve path

Where v1 corresponds to the Mirror Node REST API version and docs is the default path value as controlled by hedera.mirror.rest.openapi.swaggerUIPath.

Update Spec

To update the spec, manually modify the spec file located at

  • hedera-mirror-rest/api/v1/openapi.yml

Where v1 corresponds to the Mirror Node REST API version and openapi is the default filename value as controlled by hedera.mirror.rest.openapi.specFileName.

  • hedera-mirror-rest/api/v1/openapi.yml - API v1 openapi spec

Metrics

The REST API has metrics as provided by Swagger Stats. Using this 3 endpoints are made available

  • /swagger/ui - Metrics dashboard
  • /swagger/stats - Aggregated statistics
  • /swagger/metrics - Prometheus formatted metrics

Where swagger is the default metrics path as controlled by hedera.mirror.rest.metrics.config.uriPath.

Rosetta API

Initial Installation / Upgrade

The Rosetta API runs on Go and should be able to run on any platform that Golang supports. That said, we recommend Ubuntu 22.04 be used as the base operating system as that is the only OS we've tested against.

tar -xvf hedera-mirror-rosetta-v*.tgz
cd hedera-mirror-rosetta-*/scripts
sudo ./deploy.sh

File Layout

  • /usr/lib/hedera-mirror-rosetta - Binaries
  • /usr/etc/hedera-mirror-rosetta/application.yml - Configuration file

Starting

sudo systemctl start hedera-mirror-rosetta.service

The Rosetta API container will display logs similar to the below at start:

Successfully connected to Database
Serving Rosetta API in ONLINE mode
Listening on port 5700

Stopping

sudo systemctl stop hedera-mirror-rosetta.service

Monitoring

systemctl status hedera-mirror-rosetta.service
sudo journalctl -fu hedera-mirror-rosetta.service

Verifying

The REST API endpoints can be verified through the terminal using the curl command. The following endpoint is a suggestion to get the genesis block. Modify the below IP's and ports if they differ from your running containers.

curl -H "Content-Type: application/json" -d '{ "network_identifier": {"blockchain":"Hedera", "network": "testnet", "sub_network_identifier": { "network": "shard 0 realm 0" }}, "block_identifier": {"index":0} }' 'http://localhost:5700/block'