Legacy project config file (run.xml)

Run.XML defines a run-time configuration of a Rell node. The configuration consists of two key parts:

1. The list of Postchain nodes (the target node is one of those nodes).
2. The list of blockchains, each having an associated configuration and a Rell app.

This file gets used:

• By Rell command-line utilities multirun.sh and multigen.sh.
• By the Eclipse IDE (which internally uses multirun.sh to launch Postchain applications).

The format

Example of a Run.XML file:

<run wipe-db="true">
    <nodes>
        <config src="config/node-config.properties" add-signers="false" />
    </nodes>
    <chains>
        <chain name="user" iid="1">
            <config height="0">
                <app module="user" />
                <gtv path="gtx/rell/moduleArgs/user">
                    <dict>
                        <entry key="foo"><bytea>0373599a61cc6b3bc02a78c34313e1737ae9cfd56b9bb24360b437d469efdf3b15</bytea></entry>
                    </dict>
                </gtv>
            </config>
            <config height="1000">
                <app module="user_1000">
                    <args module="user_1000">
                        <arg key="foo"><bytea>0373599a61cc6b3bc02a78c34313e1737ae9cfd56b9bb24360b437d469efdf3b15</bytea></arg>
                    </args>
                </app>
                <gtv path="path" src="config/template.xml"/>
            </config>
        </chain>
        <chain name="city" iid="2">
            <config height="0" add-dependencies="false">
                <app module="city" />
                <gtv path="signers">
                    <array>
                        <bytea>0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57</bytea>
                    </array>
                </gtv>
                <dependencies>
                    <dependency name="user" chain="user" />
                </dependencies>
            </config>
            <include src="config/city-include-1.xml"/>
            <include src="config/city-include-2.xml" root="false"/>
        </chain>
    </chains>
</run>

Top-level elements are:

• nodes - defines Postchain nodes
• chains - defines blockchains

Nodes

Node configuration is available in a standard Postchain node-config.properties format.

Specifying a path to an existing node-config.properties file (path is relative to the Run.XML file):

<nodes>
    <config src="config/node-config.properties" add-signers="false" />
</nodes>

Specifying node configuration properties directly, as text:

<nodes>
    <config add-signers="false">
        database.driverclass=org.postgresql.Driver
        database.url=jdbc:postgresql://localhost/postchain
        database.username=postchain
        database.password=postchain
        database.schema=test_app

        activechainids=1

        api.port=7740
        api.basepath=

        node.0.id=node0
        node.0.host=127.0.0.1
        node.0.port=9870
        node.0.pubkey=0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57

        messaging.privkey=3132333435363738393031323334353637383930313233343536373839303131
        messaging.pubkey=0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57
    </config>
</nodes>

Chains

A chain element can have multiple config elements and a dependencies element inside.

A single chain may have specific configurations assigned to specific block heights.

<config height="0" add-dependencies="false">
    <app module="city" />
    <gtv path="signers">
        <array>
            <bytea>0350fe40766bc0ce8d08b3f5b810e49a8352fdd458606bd5fafe5acdcdc8ff3f57</bytea>
        </array>
    </gtv>
</config>

An app element specifies a Rell app used by the chain. Attribute module is the name of the main module of the app. The source code of the main module and all modules it imports get injected into the generated blockchain XML configuration.

gtv elements inject GTXML fragments directly into the generated Postchain blockchain XML configuration. Attribute path specifies a dictionary path for the fragment (default is root). For example, the fragment

<gtv path="gtx/rell/moduleArgs/user">
    <dict>
        <entry key="foo"><bytea>0373599a61cc6b3bc02a78c34313e1737ae9cfd56b9bb24360b437d469efdf3b15</bytea></entry>
    </dict>
</gtv>

Creates a blockchain XML:

<dict>
    <entry key="gtx">
        <dict>
            <entry key="rell">
                <dict>
                    <entry key="moduleArgs">
                        <dict>
                            <entry key="user">
                                <dict>
                                    <entry key="foo">
                                        <bytea>0373599A61CC6B3BC02A78C34313E1737AE9CFD56B9BB24360B437D469EFDF3B15</bytea>
                                    </entry>
                                </dict>
                            </entry>
                        </dict>
                    </entry>
                </dict>
            </entry>
        </dict>
    </entry>
</dict>

GTXML contents are either specified as a nested element of a gtv element or placed in an XML file referenced via the src attribute.

Included files

You can use the include tag to include other XML files anywhere in a Run.XML file. Included files may include other XML files as well.

Including a file with its root element replacing the include element:

<include src="config/city-include-1.xml"/>

Including a file without its root element, the include gets replaced by the child elements of the root element of the file:

<include src="config/city-include-2.xml" root="false"/>

Utilities

These utilities are a part of the Rell language.

The multirun.sh file

Runs an app described by a Run.XML configuration.

Usage: RellRunConfigLaunch [-d=SOURCE_DIR] RUN_CONFIG
Launch a run config
      RUN_CONFIG   Run config file
  -d, --source-dir=SOURCE_DIR
                   Rell source code directory (default: current directory)

The multigen.sh file

Creates a Postchain blockchain XML configuration from a Run.XML configuration.

Usage: RellRunConfigGen [--dry-run] [-d=SOURCE_DIR] [-o=OUTPUT_DIR] RUN_CONFIG
Generate blockchain config from a run config
      RUN_CONFIG   Run config file
      --dry-run    Do not create files
  -d, --source-dir=SOURCE_DIR
                   Rell source code directory (default: current directory)
  -o, --output-dir=OUTPUT_DIR
                   Output directory

Example of a generated directory tree:

out/
├── blockchains
│   ├── 1
│   │   ├── 0.gtv
│   │   ├── 0.xml
│   │   ├── 1000.gtv
│   │   ├── 1000.xml
│   │   └── brid.txt
│   └── 2
│       ├── 0.gtv
│       ├── 0.xml
│       ├── 1000.gtv
│       ├── 1000.xml
│       ├── 2000.gtv
│       ├── 2000.xml
│       ├── 3000.gtv
│       ├── 3000.xml
│       └── brid.txt
├── node-config.properties
└── private.properties