Project settings file

Most configurations for your dapp are available in the project configuration file. By default, it's called chromia.yml, but you can name it to something else if there is a need to do so.

Following is an example of such a file. Remember that most attributes have default values and don't need to be configured unless you want to override the default behavior.

note

These files are taken from Build and run the Hello World dapp with Chromia CLI.

`blockchains`

This section defines the blockchains used in your project. Each blockchain has a unique name, specifying the entry point module, configuration options, block strategies, and module arguments.

Example minimum file:

blockchains:
  hello: #Name of the blockchain
    module: main #Entrypoint to the project

Example full file:

blockchains:
  <blockchain_name_1>:
    module: main
    moduleArgs:
      <name.of.module_1>:
        <name_of_argument_1>: x"<value>"
        <name_of_argument_2>: x"<value>"
      <name.of.module_2>:
        <name_of_argument_1>: x"<value>"
        <name_of_argument_2>: x"<value>"
    config:
      <config name>: <value>
    test:
      modules:
        - <name.of.test.module_1>
        - <name.of.test.module_2>
      moduleArgs:
        <name.of.module>:
          <name_of_argument_1>: x"<value>"
      failOnError: true

`<blockchain_name>`

The name of the individual blockchain you are configuring is a mandatory field that identifies the specific blockchain within the list.

`<blockchain>:module`

Specifies the module responsible for interacting with the chosen blockchain.

`<blockchain>:moduleArgs`

This field defines the arguments to be passed to the specified module. It's an optional field. However, note that you can't access the args field in the module if the moduleArgs structure isn't defined.

`<blockchain>:config`

Allows you to specify any specific configuration settings for the chosen blockchain. It's an optional field. Each setting uses a <config name> paired with a corresponding <GTV Value>. See the blockchain configuration topic for more information.

`<blockchain>:test`

This section defines the tests to be executed for the blockchain. See the test section for more information.

`deployments`

This section configures deployment targets for your blockchains. Each deployment defines the target blockchain RID, URLs, container ID, and deployed chains with their respective RIDs.

Example:

deployments:
  <deployment_name_1>:
    brid: x"<BlockchainRid>"
    url:
      - <TargetURL>
      - <TargetURL>
    container: <containerIID>
    chains:
      <blockchain_name_1>: x"<BlockchainRid>" # Name should match field in blockchains. In this case, blockchain_name_1.
      <blockchain_name_2>: x"<BlockchainRid>"
  <deployment_name_2>:
    brid: x"<BlockchainRid>"
    url: <TargetURL>
    container: <containerIID>

`<deployment_name>`

The deployment target's name acts as a unique identifier for your deployed configuration. It can be any descriptive name to distinguish between different environments or setups.

`<deployment>:brid`

Defines the Blockchain RID (Referential ID) of the management chain for the target network. For example, x"1212121212121212121212121212121212121212121212121212121212121212".

`<deployment>:url`

A list of strings of Target URLs for accessing the deployed application on the specified blockchain network.

Example:

url: https://node1:7740
url:
  - https://node1:7740
  - https://node2:7740

`<deployment>:container`

Specifies the Container ID of the container.

`<deployment>:chains`

Defines the individual blockchains deployed on this target. The keys of the dict must match a key in blockchains.

Valid example:

blockchains:
  my-chain:
    module: main
deployments:
  network1:
    url: http://localhost:7740
    brid: x"ABAB"
    chains:
      my-chain: x"121212"

Invalid example:

blockchains:
  my-chain:
    module: main
deployments:
  network1:
    url: http://localhost:7740
    brid: x"ABAB"
    chains:
      my-other-chain: x"121212"

`compile`

This section configures deployment targets for your blockchains. Each deployment defines the target blockchain RID, URLs, container ID, and deployed chains with their respective RIDs.

Example:

compile:
  rellVersion: 0.13.5
  source: src
  target: build
  deprecatedError: false
  quiet: true
  strictGtvConversion: true

`compile:rellVersion`

Specifies the Rell version.

`compile:source`

Defines the relative path to the directory containing your dapp source code files.

`compile:target`

Defines the relative path to the directory where the compiled artifacts will be generated.

`compile:deprecatedError`

This controls whether the compiler throws errors upon encountering deprecated syntax or features. Setting it to true causes a build failure if deprecated features are used.

`compile:quiet`

Decides on the compiler messages during the compilation process. Set it to true if you don't want to see intermediary compilation output.

`compile:strictGtvConversion`

This controls the use of strict GTV conversion when parsing operation arguments; it is recommended that you leave this to true (the default). See type conversions for more details.

note

This option is only available from Rell 0.13.9. Before, it behaved as if this option was set to false.

`database`

This section configures the PostgreSQL database connection settings for your project. It defines the password, username, database name, host, logging behavior for SQL errors, schema name, and database driver.

Example:

database:
  password: postchain
  username: postchain
  database: postchain
  host: localhost
  logSqlErrors: true
  schema: rell_app
  driver: org.postgresql.Driver

`database:password`

The password for the database user.

`database:username`

The username for the database.

`database:database`

The name of the database to connect to.

`database:host`

The hostname or IP address of the database server.

`database:logSqlErrors`

Specifies whether to log SQL errors encountered during database interaction. If set to true, it enables logging of SQL errors encountered during database interaction. This can be helpful for debugging issues.

`database:schema`

The database schema containing your dapp's tables and data.

`database:driver`

The Java class name for the JDBC driver used to connect to the PostgreSQL database.

warning

Consider storing sensitive information like passwords in secure environments instead of directly in the YAML file.

Database variables

You might want to store PostgreSQL database settings as environment variables instead of saving them in the chromia.yml file for various reasons, such as security.

In that case, you can set values by entering export ENV_VAR_NAME=env_var_value in the terminal or adding the commands to your ~/.bashrc file. For example,

export CHR_DB_URL=URL
export CHR_DB_USER=user
export CHR_DB_PASSWORD='pwd'
export CHR_DB_SCHEMA=app

These values override the values that are present in chromia.yml.

`test`

This section defines the tests to be executed for your project. It lists the test modules, allows specifying arguments for specific modules, and enables test failure termination.

Example:

test:
  modules:
    - <name.of.test.module_1>
    - <name.of.test.module_2>
  moduleArgs:
    <name.of.module>:
      <name_of_argument_1>: x"<value>"
  failOnError: true

`test:modules`

List of test modules to be executed. Each module is represented by its filename relative to the test directory.

`test:moduleArgs`

Allows you to pass arguments to individual test modules.

`test:failOnError`

Determines whether the entire test run should fail if any individual test case fails.

tip

Consider using descriptive names for tests and modules for clarity.

Test module arguments

If a method needs arguments, they can be specified in the moduleArgs key. For example, if you have a test query method in a module called arg_test.rell in the test folder, that looks as follows:

@test module;
struct module_args {
    value: integer;
}

function test_foo() {
    assert_equals(2 + 2, chain_context.args.value);
}

Then the test key would look like this, for that project:

test:
  modules:
    - test.arg_test
  moduleArgs:
    test.arg_test:
      value: 4

note

You can also add tests to a specific blockchain in your project as follows:

blockchains:
  my_chain:
    module: main
    test:
      modules:
        - main.test
      moduleArgs: ...

moduleArgs overrides the project-level test module with the ones that are defined in the blockchain.

`libs`

This section defines external libraries used in your project. It specifies the library name, registry URL, path within the repository, optional branch or tag, RID, and insecure download verification option.

Example:

libs:
  <library_name>:
    registry: <url to git repository>
    path: <path to library inside the repository>
    tagOrBranch: <value>
    rid: x"<value>"
    insecure: false

`<library_name>`

List of test modules to be executed. Each module is represented by its filename relative to the test directory.

`<lib>:registry`

Specifies the URL of the Git repository containing the library source code. Ensure the repository holds the relevant library files.

`<lib>:path`

Defines the specific path within the repository where the library files reside.

`<lib>:tagOrBranch`

Allows you to specify a particular branch or tagged version of the Git repository to download. By default, the latest commit on the master branch will be used.

`<lib>:rid`

The GTV hash of the complete library's Rell files.

`<lib>:insecure`

Allows you to bypass the cryptographic hash check against the rid. Setting it to true turns off verification, which is not recommended for production usage as it compromises safety and version control.

`docs`

This section describes the configuration for generate docs-site.

`docs:title`

Specifies the title of the generated site.

`docs:footerMessage`

Specifies a string to be shown in the footer of the generated site.

`docs:customStyleSheets`

Include any custom style sheets. Use this to override the existing styles to personalize your site.

`docs:customAssets`

Include any files you want to be included in the generated site. The files will be moved to the images folder of the generated site.

`docs:additionalContent`

A list of markdown files that is used to populate the main page and the rell module sections.

Example

my-doc.md
// Name must match the title of the site

# Dapp <My Rell Dapp>

// Content

# Module <module-1>

// Content shown on the start page and module page // Content shown on the module page

## Sub-titles are allowed

// Content

# Module <module-2>

// Content

`docs:sourceLink`

`docs:sourceLink:remoteUrl`

URL of the source code corresponding to this code base. The URL should include the path to the project's source folder.

Example

https://github.com/my-repo/blob/main/src/

`docs:sourceLink:remoteLineSuffix`

String corresponding to the line suffix used by the Git project as a divider between the URL and the line number. Typically, one of the:

Github: "#L"
Gitlab: "#L"
Bitbucket: "#lines-"

YAML anchors

It's possible to use YAML anchoring, as shown in the example below, where the tests are anchored to the definitions key in the file. Any anchored value must be in the definitions key.

Example:

definitions: #Used for YAML anchors in this file
  modules: &test
    - test.arithmetic_test
    - test.data_test

blockchains:
  hello:
    module: main
test:
  modules: *test

Include another YAML configuration

To include another YAML configuration, you can use the !include tag.

#test.yml
a: 13
b: 15

#chromia.yml
blockchains:
  hello:
    module: main
test:
  modules: !include test.yml

You get:

#chromia.yml
blockchains:
  hello:
    module: main
test:
  modules:
    a: 13
    b: 15

You can also include a specific tag from another YAML file. For example:

#test.yml
a: 13
b: 15

#chromia.yml
blockchains:
  hello:
    module: main
test:
  modules: !include test.yml#a

You get:

#chromia.yml
blockchains:
  hello:
    module: main
test:
  modules: 13

blockchains​

Example minimum file:​

Example full file:​

<blockchain_name>​

<blockchain>:module​

<blockchain>:moduleArgs​

<blockchain>:config​

<blockchain>:test​

deployments​

Example:​

<deployment_name>​

<deployment>:brid​

<deployment>:url​

Example:​

<deployment>:container​

<deployment>:chains​

Valid example:​

Invalid example:​

compile​

Example:​

compile:rellVersion​

compile:source​

compile:target​

compile:deprecatedError​

compile:quiet​

compile:strictGtvConversion​

database​

Example:​

database:password​

database:username​

database:database​

database:host​

database:logSqlErrors​

database:schema​

database:driver​

Database variables​

test​

Example:​

test:modules​

test:moduleArgs​

test:failOnError​

Test module arguments​

libs​

Example:​

<library_name>​

<lib>:registry​

<lib>:path​

<lib>:tagOrBranch​

<lib>:rid​

<lib>:insecure​

docs​

docs:title​

docs:footerMessage​

docs:customStyleSheets​

docs:customAssets​

docs:additionalContent​

Example​

docs:sourceLink​

docs:sourceLink:remoteUrl​

Example​

docs:sourceLink:remoteLineSuffix​

YAML anchors​

Example:​

Include another YAML configuration​

`blockchains`

Example minimum file:

Example full file:

`<blockchain_name>`

`<blockchain>:module`

`<blockchain>:moduleArgs`

`<blockchain>:config`

`<blockchain>:test`

`deployments`

Example:

`<deployment_name>`

`<deployment>:brid`

`<deployment>:url`

Example:

`<deployment>:container`

`<deployment>:chains`

Valid example:

Invalid example:

`compile`

Example:

`compile:rellVersion`

`compile:source`

`compile:target`

`compile:deprecatedError`

`compile:quiet`

`compile:strictGtvConversion`

`database`

Example:

`database:password`

`database:username`

`database:database`

`database:host`

`database:logSqlErrors`

`database:schema`

`database:driver`

Database variables

`test`

Example:

`test:modules`

`test:moduleArgs`

`test:failOnError`

Test module arguments

`libs`

Example:

`<library_name>`

`<lib>:registry`

`<lib>:path`

`<lib>:tagOrBranch`

`<lib>:rid`

`<lib>:insecure`

`docs`

`docs:title`

`docs:footerMessage`

`docs:customStyleSheets`

`docs:customAssets`

`docs:additionalContent`

Example

`docs:sourceLink`

`docs:sourceLink:remoteUrl`

Example

`docs:sourceLink:remoteLineSuffix`

YAML anchors

Example:

Include another YAML configuration