# Project settings file · Chromia Docs (concept)

> Most configurations for your dapp are available in the project configuration file.

Source: https://docs.chromia.com/build/configuration/project-config/

# Project settings file

On this page

* [blockchains](#blockchains)
* [<blockchain\_name>](#blockchain_name)
* [<blockchain>:module](#blockchainmodule)
* [<blockchain>:moduleArgs](#blockchainmoduleargs)
* [<blockchain>:config](#blockchainconfig)
* [<blockchain>:test](#blockchaintest)
* [deployments](#deployments)
* [<deployment\_name>](#deployment_name)
* [<deployment>:brid](#deploymentbrid)
* [<deployment>:url](#deploymenturl)
* [<deployment>:container](#deploymentcontainer)
* [<deployment>:chains](#deploymentchains)
* [compile](#compile)
* [compile:rellVersion](#compilerellversion)
* [compile:source](#compilesource)
* [compile:target](#compiletarget)
* [compile:deprecatedError](#compiledeprecatederror)
* [compile:quiet](#compilequiet)
* [compile:strictGtvConversion](#compilestrictgtvconversion)
* [database](#database)
* [database:password](#databasepassword)
* [database:username](#databaseusername)
* [database:database](#databasedatabase)
* [database:host](#databasehost)
* [database:logSqlErrors](#databaselogsqlerrors)
* [database:schema](#databaseschema)
* [database:driver](#databasedriver)
* [test](#test)
* [test:modules](#testmodules)
* [test:failOnError](#testfailonerror)
* [test:moduleArgs](#testmoduleargs)
* [libs](#libs)
* [Library-chain libraries](#library-chain-libraries)
* [External Git libraries](#external-git-libraries)
* [<library\_name>](#library_name)
* [<lib>:registry](#libregistry-1)
* [<lib>:path](#libpath)
* [<lib>:tagOrBranch](#libtagorbranch)
* [<lib>:rid](#librid)
* [<lib>:insecure](#libinsecure)
* [docs](#docs)
* [docs:title](#docstitle)
* [docs:footerMessage](#docsfootermessage)
* [docs:customStyleSheets](#docscustomstylesheets)
* [docs:customAssets](#docscustomassets)
* [docs:additionalContent](#docsadditionalcontent)
* [docs:sourceLink](#docssourcelink)
* [docs:sourceLink:remoteUrl](#docssourcelinkremoteurl)
* [docs:sourceLink:remoteLineSuffix](#docssourcelinkremotelinesuffix)
* [YAML anchors](#yaml-anchors)
* [Include another YAML configuration](#include-another-yaml-configuration)

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.

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

YAML

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

#### Example full file:

YAML

```
blockchains:
  <blockchain_name_1>:
    module: main
    moduleArgs:
      <name.of.module_1>:
        <name_of_argument_1>: <value>
        <name_of_argument_2>: <value>
      <name.of.module_2>:
        <name_of_argument_1>: <value>
        <name_of_argument_2>: <value>
    config:
      features:
        merkle_hash_version: 2
      <config_name>: <value>
    test:
      modules:
        - <name.of.test.module_1>
        - <name.of.test.module_2>
      moduleArgs:
        <name.of.module>:
          <name_of_argument_1>: <value>
      failOnError: true
```

### `<blockchain_name>`

> ***Input:*** string

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

### `<blockchain>:module`

> ***Input:*** string

Specifies blockchains entry point by module. Everything that is directly, or indirectly, imported by the module will be
included in the blockchain.

### `<blockchain>:moduleArgs`

> ***Input:*** dict

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.

#### Example:

With module arguments defined as:

YAML

```
moduleArgs:
  <module_name>:
    <name_of_argument_1>: <value>
    <name_of_argument_2>: <value>
```

The module `<moudle_name>` needs to have the following struct defined to be able to access the arguments:

Rell

```
struct module_args {
    <name_of_argument_1>: <type>
    <name_of_argument_2>: <type>
}
```

Then you can access it through the [`chain_context`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/chain_context/)

Rell

```
operation foo() {
    val arg_one = chain_context.args.name_of_argument_1;
    val arg_two = chain_context.args.name_of_argument_2;
}
```

### `<blockchain>:config`

> ***Input:*** dict

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](https://docs.chromia.com/build/configuration/blockchain-properties/) topic for more information.

### `<blockchain>:test`

> ***Input:*** dict

This section defines the tests to be executed for the blockchain. See the [test](#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.

If you are configuring a deployment towards `mainnet` or `testnet`, you can use the predefined network names: `mainnet`
or `testnet`. This will automatically use the correct blockchain RID and URL for the chosen network, when used together
with `chromia-cli`.

info

For verification of the `brid` and `url`, follow these steps:

* Visit the [Chromia Explorer](https://explorer.chromia.com) and set **Current network** to **Mainnet**.
* Under **Clusters**, select **system**.
* Copy an **API URL** from the bottom of the page (e.g., **https://system.chromaway.com**) and use it
  as the `url`.
* Under **System Chains**, click **directory\_chain** and copy the `brid`.

#### Mainnet Example:

YAML

```
deployments:
  mainnet: #Values of mainnet//testnet, will use the correct blockchain RID and URL for the chosen network.
    container: <containerIID>
    chains:
      <blockchain_name>: x"<BlockchainRid>"
```

#### Complete Example:

YAML

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

> ***Input:*** string

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.

Using `mainnet` or `testnet` as the deployment name will reduce the number of fields you need to configure. Take a look
at the [Mainnet Example](#mainnet-example) for more information.

### `<deployment>:brid`

> ***Input:*** byte\_array (Hexadecimal string representation of a byte\_array.)

Defines the Blockchain RID (Referential ID) of the directory chain for the targeted network.

Mainnet: x"7E5BE539EF62E48DDA7035867E67734A70833A69D2F162C457282C319AA58AE4" Testnet: x"6F1B061C633A992BF195850BF5AA1B6F887AEE01BB3F51251C230930FB792A92"

### `<deployment>:url`

> ***Input:*** list of strings or string

A list of strings of system node URLs for the targeted network.

#### Example:

YAML

```
url: https://system.chromaway.com
url:
  - https://system.chromaway.com
  - https://mainnet-dapp1.sunube.net:7740
```

You can find the list of public nodes on the [Chromia Explorer](https://explorer.chromia.com/mainnet/cluster/system).

### `<deployment>:container`

> ***Input:*** string

Specifies the Container ID of the container.

### `<deployment>:chains`

> ***Input:*** dict (string to hex-string)

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

note

For the first deployment this field is not required. During the deployment process, the `chromia-cli` will prompt you
with the `BlockchainRid` of the deployed blockchain. And how to add it to the `chromia.yml` file.

If you lost your `BlockchainRid`, you can find it in [Chromia Explorer](https://explorer.chromia.com/mainnet).

#### Valid example:

YAML

```
blockchains:
  my-chain:
    module: main
deployments:
  network1:
    url: http://localhost:7740
    brid: x"<BlockchainRid>"
    chains:
      my-chain: x"<BlockchainRid>"
```

#### Invalid example:

YAML

```
blockchains:
  my-chain:
    module: main
deployments:
  network1:
    url: http://localhost:7740
    brid: x"<BlockchainRid>"
    chains:
      my-other-chain: x"<BlockchainRid>"
```

## `compile`

This section configures the Rell compiler settings for your project. It specifies the Rell version to use, source and
output directory paths, and various compiler behavior options such as handling deprecated syntax and controlling
compilation output verbosity.

#### Example:

YAML

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

### `compile:rellVersion`

> ***Input:*** string (semver)

Specifies the Rell version.

### `compile:source`

> ***Input:*** string

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

### `compile:target`

> ***Input:*** string

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

### `compile:deprecatedError`

> ***Input:*** boolean

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`

> ***Input:*** boolean

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`

> ***Input:*** boolean

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](https://docs.chromia.com/get-started/about/protocols/gtv/) 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 when running your project locally. It defines the
password, username, database name, host, logging behavior for SQL errors, schema name, and database driver.

#### Default Example

If you have setup your PostgreSQL database by following our setup guide with default values, the minimal database
configuration in `chromia.yml` may look like this:

YAML

```
database:
  schema: <schema_name>
```

#### Complete Example:

YAML

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

### `database:password`

> ***Input:*** string

The password for the database user.

### `database:username`

> ***Input:*** string

The username for the database.

### `database:database`

> ***Input:*** string

The name of the database to connect to.

### `database:host`

> ***Input:*** string

The hostname or IP address of the database server.

### `database:logSqlErrors`

> ***Input:*** boolean

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`

> ***Input:*** string

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

### `database:driver`

> ***Input:*** string

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,

Terminal

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

> We also support environment variables for string substitution in `chromia.yml`. It follows the following schema:
> `foo: ${MY_VAR:-default_var}`.

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

note

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

YAML

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

#### Example:

YAML

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

> ***Input:*** string

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

### `test:failOnError`

> ***Input:*** boolean

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

> ***Input:*** dict

Allows you to pass in test values for modules that require module arguments. You can also pass in module arguments into
test modules.

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

Rell

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

YAML

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

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

## `libs`

This section defines libraries used in your project. Chromia supports two types of libraries:

1. **Library-chain libraries** - Published to Chromia's library registry (recommended)
2. **External Git libraries** - Hosted in Git repositories

info

The
[Library Chain](https://explorer.chromia.com/mainnet/C9051571CD822507DDD1F3B43F2DC066B54CC5A25ECD758A1B5A42913483CF20)
is a complete dapp deployed on the Chromia blockchain that hosts the official library registry. You can discover and
install libraries using the [library commands](https://docs.chromia.com/build/cli/library/).

### Library-chain libraries

Published libraries from Chromia's library registry provide versioned, verified packages with cryptographic integrity
checks.

#### Example:

YAML

```
libs:
  <library_id>: # The library ID as it appears in the registry
    version: <version of the library to install>
    registry: <network (mainnet/testnet) where the library-chain is deployed>
    brid: x"<BlockchainRid of the library-chain if deployed on custom network>"
```

#### `<library_id>`

> ***Input:*** string

The unique identifier of the library from the registry (e.g., `com.chromia.ft4`). This is the top-level key for each
library configuration.

#### `<lib>:version`

> ***Input:*** string

Specifies the version of the library to install. This is a required field for library-chain libraries.

#### `<lib>:registry`

> ***Input:*** string

Specifies the network or URL where the library-chain is deployed. Can be:

* Predefined network names: `mainnet` (default), `testnet`, or `localhost`
* Custom URL: e.g., `https://custom-network.com:7740`

If not provided, it defaults to `mainnet`.

#### `<lib>:brid`

> ***Input:*** byte\_array (Hexadecimal string representation of a byte\_array.)

The blockchain RID of the library-chain. Required only when using a custom registry URL. Not needed for predefined
Chromia networks (`mainnet`, `testnet`, `localhost`).

### External Git libraries

Libraries hosted in Git repositories provide flexibility for custom or private libraries not published to the registry.

#### Example:

YAML

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

### `<library_name>`

> ***Input:*** string

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

### `<lib>:registry`

> ***Input:*** string

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

### `<lib>:path`

> ***Input:*** string

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

### `<lib>:tagOrBranch`

> ***Input:*** string

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

### `<lib>:rid`

> ***Input:*** byte\_array (Hexadecimal string representation of a byte\_array. For example: `x”ABABABA”`.)

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

### `<lib>:insecure`

> ***Input:*** boolean

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](https://docs.chromia.com/build/cli/commands/generate/#generate-docs-site).

### `docs:title`

> ***Input:*** string

Specifies the title of the generated site.

### `docs:footerMessage`

> ***Input:*** string

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

### `docs:customStyleSheets`

> ***Input:*** list of strings

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

### `docs:customAssets`

> ***Input:*** list of strings

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`

> ***Input:*** list of strings

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

#### Example

my-doc.mdMarkdown

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

> ***Input:*** string

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

#### Example

Plain text

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

### `docs:sourceLink:remoteLineSuffix`

> ***Input:*** string

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:

YAML

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

YAML

```
#test.yml
a: 13
b: 15
```

YAML

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

You get:

YAML

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

YAML

```
#test.yml
a: 13
b: 15
```

YAML

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

You get:

YAML

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

[View this page on docs.chromia.com](https://docs.chromia.com/build/configuration/project-config/)Content mirrored from the live docs
