# Set up your project · Verify events across chains with ICCF · Learn Chromia

> You need the following in place before you begin:

Source: https://chromia.com/learn/iccf-course/setup/

Verify events across chains with ICCFLesson 2 of 6

1. [01Confirm Events Across Blockchains](https://chromia.com/learn/iccf-course/introduction/)
2. [02Set up your project](https://chromia.com/learn/iccf-course/setup/)
3. [03System overview](https://chromia.com/learn/iccf-course/system-overview/)
4. [04Subscription chain](https://chromia.com/learn/iccf-course/subscription-chain/)
5. [05Digital warehouse chain](https://chromia.com/learn/iccf-course/digital-warehouse-chain/)
6. [06Testing the dapp](https://chromia.com/learn/iccf-course/manual-testing/)

[Learn](https://chromia.com/learn/)[Verify events across chains with ICCF](https://chromia.com/learn/iccf-course/)

02 / 06Intermediate

# Set up your project

You need the following in place before you begin:

Set up a PostgreSQL database

## Set up a PostgreSQL database

Rell needs PostgreSQL 16.3. You can use the IDE without a database, but you cannot run a node from it. A console or a remote postchain app does not need a database.

Rell expects these database settings by default:

* database: `postchain`
* user: `postchain`
* password: `postchain`

## Install

1. Install Homebrew by following the [Homebrew setup instructions](https://brew.sh/).
2. Install PostgreSQL:

   shell

   ```
   brew install postgresql@16
   brew services start postgresql@16
   createuser -s postgres
   ```
3. Create the database and user:

   plsql

   ```nolines
   psql -U postgres -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'C.UTF-8' LC_CTYPE = 'C.UTF-8' ENCODING 'UTF-8';" -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
   ```

   note

   A "peer authentication failed" error means you need to switch the authentication method from `peer` to `md5`. Make this change in the `pg_hba.conf` file of your `psql` database.

1. Install PostgreSQL:

   bash

   ```nolines
   sudo apt install postgresql-16
   ```
2. Create the database and user:

   bash

   ```nolines
   sudo -u postgres psql -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'C.UTF-8' LC_CTYPE = 'C.UTF-8' ENCODING 'UTF-8';" -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
   ```

1. Install Docker by following the [Docker setup instructions](https://docs.docker.com/engine/install/).
2. Create the database and user:

   dockerfile

   ```nolines
   docker run --name postgres -e POSTGRES_USER=postchain -e POSTGRES_PASSWORD=postchain -p 5432:5432 -d postgres:16.3-alpine3.20
   ```

   note

   The Alpine image of PostgreSQL is used here because its default collation settings are the right ones. You can also set the collation explicitly with this environment variable:

   bash

   ```nolines
   POSTGRES_INITDB_ARGS="--lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --encoding=UTF-8"
   ```

1. Get the PostgreSQL installer from the [PostgreSQL download page](https://www.postgresql.org/download/windows/).
2. Run the installer, then add the PostgreSQL folder that holds the binaries to your environment variables. In Command Prompt (CMD), run the command below. Check that the path points to your binaries and replace `<version>` with the version you installed:

   shell

   ```nolines
   setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"
   ```
3. Close and reopen Command Prompt (CMD) so it picks up the new environment variables. Then create the database and user by running these two commands one after the other:

   plsql

   ```nolines
   psql -U postgres -c "CREATE DATABASE postchain WITH TEMPLATE = template0 LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' ENCODING 'UTF-8';"
   psql -U postgres -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
   ```

   note

   On some Windows versions, you may hit permission errors or problems caused by a faulty PostgreSQL installation. In that case, install Docker and run PostgreSQL in a container instead.

Install the Chromia CLI

## Install the Chromia CLI

The steps below show how to install and update the [Chromia CLI](https://gitlab.com/chromaway/core-tools/chromia-cli).

## Prerequisite

Check that you have the following before you continue:

* **PostgreSQL database**: Follow [Set up a PostgreSQL database](https://docs.chromia.com/get-started/installation/#set-up-postgresql-database).
* **RELL\_JAVA environment**: The Chromia CLI needs a Java runtime, version 21 or later. The package managers take care of this, so you normally don't have to configure it. To choose which Java runtime runs the Chromia CLI, set the RELL\_JAVA environment variable to a valid Java installation.

## Installation

Install the Chromia CLI through a package manager, or download it from [the Chromia CLI package registry](https://gitlab.com/chromaway/core-tools/chromia-cli/-/packages).

On macOS, install the Chromia CLI (`chr`) as follows:

1. If you don't have Homebrew yet, install it:

   bash

   ```nolines
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
2. Register the Chromia repository with Homebrew:

   bash

   ```nolines
   brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git
   ```
3. Install the Chromia CLI:

   bash

   ```nolines
   brew install chromia/core/chr
   ```

   info

   To pin a specific Chromia CLI version, run these commands:

   shell

   ```
   brew install chromia/core/chr@<version>
   brew unlink chr
   brew link chr@<version>
   ```

   Run `brew search chr` to see which versions are available.
4. Confirm the installation by printing the version:

   bash

   ```nolines
   chr --version
   ```

On Linux or WSL (Windows Subsystem for Linux), install the Chromia CLI (`chr`) as follows:

1. Fetch the public key for Chromia's `apt-repo` and add it to your trusted keyrings:

   bash

   ```nolines
   curl -fsSL https://apt.chromia.com/chromia.gpg | sudo tee /usr/share/keyrings/chromia.gpg
   ```
2. Add the Chromia repository to your package sources:

   bash

   ```nolines
   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/chromia.gpg] https://apt.chromia.com stable main" | sudo tee /etc/apt/sources.list.d/chromia.list
   ```
3. Refresh your package sources:

   bash

   ```nolines
   sudo apt-get update
   ```

   info

   If you added `apt.chromia.com` before Chromia CLI version `0.16.0`, run this command so the repository can update:

   bash

   ```nolines
   sudo apt-get --allow-releaseinfo-change update
   ```
4. After the update completes, install the Chromia CLI:

   bash

   ```nolines
   sudo apt-get install chr
   ```
5. Confirm the installation by printing the version:

   bash

   ```nolines
   chr --version
   ```

On Windows, install the Chromia CLI (`chr`) with [Scoop](https://scoop.sh/) as follows:

1. If you don't have Scoop yet, open PowerShell as Administrator and run:

   powershell

   ```nolines
   iwr -useb get.scoop.sh | iex
   ```
2. Add the Chromia bucket to Scoop:

   powershell

   ```nolines
   scoop bucket add chromia https://gitlab.com/chromaway/core-tools/scoop-chromia/
   ```
3. Add the Java bucket to Scoop:

   powershell

   ```nolines
   scoop bucket add java
   ```

   With this bucket in place, Scoop can download openjdk21, which chromia-cli needs during installation.
4. Install the Chromia CLI:

   powershell

   ```nolines
   scoop install chr
   ```
5. Confirm the installation by printing the version:

   powershell

   ```nolines
   chr --version
   ```

## Updating Chromia CLI

Download the newest Chromia CLI from [the package registry](https://gitlab.com/chromaway/core-tools/chromia-cli/-/packages). If you installed it with a package manager, update it with the command for your platform:

shell

```nolines
brew update
brew upgrade chr
```

shell

```nolines
sudo apt-get update
sudo apt-get install chr
```

shell

```nolines
scoop update
scoop update chr
```

## Docker

With Docker, you can run a self-contained Linux container that already includes the Chromia CLI. You still need a [PostgreSQL database](https://docs.chromia.com/get-started/installation/#set-up-postgresql-database) set up.

The published images require Docker to be installed and configured on your host. The Docker documentation explains how to [get Docker](https://docs.docker.com/get-docker/) on Windows, Mac, and Linux.

### Start the Docker container with Chromia CLI pre-installed

To run the latest Chromia CLI, call `docker run` with the CLI image name followed by `chr`.

shell

```nolines
docker run --rm -v $(pwd):/usr/app registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:<latest version> chr
```

Windows Command Prompt Users

Windows Command Prompt (cmd) does not understand the `$(pwd)` syntax. Use one of these instead:

* **PowerShell**: `$(Get-Location)` or `$(pwd)`
* **Command Prompt**: `%CD%`

**Command Prompt example:**

cmd

```nolines
docker run --rm -v %CD%:/usr/app registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:<latest version> chr
```

note

Set up your `chromia.yml` file for your platform:

* **Mac**: set `database:host` to `host.docker.internal`.
* **Windows**: set `database:host` to `host.docker.internal` (Docker Desktop). If the node still cannot reach your database, try `172.17.0.1`, the default Docker bridge address on Linux.
* **Linux**: pass `--network=host` to your Docker commands.

Without these settings, the Chromia CLI cannot reach the PostgreSQL instance.

To update or remove the Docker image, consult the [Docker CLI reference](https://docs.docker.com/engine/reference/commandline/docker/).

bash

```
#!/bin/bash

# Allocate a pseudo-TTY one when run in interactive mode
if [ -t 0 ] && [ -t 1 ] ; then TTY="--tty"; else TTY=""; fi

docker run \
  # Sets the network to host to not need to change the database hostname (linux only)
  --network=host \
  # Set timezone based on system settings (linux only)
  -e TZ=$(cat /etc/timezone) \
  # Sets process ownership to current user
  --user $(id -u):$(id -g) \
  --mount type=bind,source="/etc/passwd",target=/etc/passwd,readonly \
  --mount type=bind,source="/etc/group",target=/etc/group,readonly \
  # Configures ssh-agent (only needed if chr install is called on non-public repositores)
  -e SSH_AUTH_SOCK=$SSH_AUTH_SOCK \
  --volume "$SSH_AUTH_SOCK:$SSH_AUTH_SOCK" \
  --mount type=bind,source="${HOME}/.ssh",target=${HOME}/.ssh,readonly \
  --mount type=bind,source="${HOME}/.config/jgit",target=${HOME}/.config/jgit \
  # Mounts current folder into the container (Use `Get-Location` on PowerShell)
  --mount type=bind,source="$(pwd)",target=/usr/app \
  --interactive ${TTY} \
  --rm \
  registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:${CHR_VERSION:-latest} chr "$@"
```

Windows Command Prompt Users

The bash script above relies on `$(pwd)`, which Windows Command Prompt does not support. On Windows:

* **PowerShell**: run the script unchanged
* **Command Prompt**: change `$(pwd)` to `%CD%` in the mount argument

**Mount line adjusted for Command Prompt:**

cmd

```nolines
--mount type=bind,source="%CD%",target=/usr/app \
```

Start by creating the project for your blockchain app:

1. Make a new project directory and switch to it in your terminal:

shell

```nolines
chr create-rell-dapp digital_warehouse_example --template=plain
```

shell

```nolines
cd digital_warehouse_example
```

2. Set up the ICCF library by adding this configuration to `chromia.yml`:

yaml

```
libs:
  iccf:
    registry: https://gitlab.com/chromaway/core/directory-chain
    path: src/lib/iccf
    tagOrBranch: 1.87.0
    rid: x"9C359787B75927733034EA1CEE74EEC8829D2907E4FC94790B5E9ABE4396575D"
  iccf_test:
    registry: https://gitlab.com/chromaway/core/directory-chain
    path: src/lib/test/iccf
    tagOrBranch: 1.87.0
    rid: x"873D71557531E35E453587FA71C2D3CCB674F0EB49D18B30FA838C52C1155EB3"
```

Then run `chr install` to fetch the `iccf` library, which you need for confirming transactions.

For reference, here are the project structure and the full `chromia.yml` file after these changes. Compare them with your own to spot differences:

Project structure

text

```
digital_warehouse_example/
├── build/
├── src/
│   ├── lib/
│   ├── test/
│   └── main.rell
├── .gitignore
└── chromia.yml
```

Final version of the `chromia.yml` file

text

```
yaml title="chromia.yml"
blockchains:
  digital_warehouse_example:
    module: main
compile:
  rellVersion: 0.14.9
database:
  schema: schema_digital_warehouse_example
test:
  modules:
    - test
libs:
  iccf:
    registry: https://gitlab.com/chromaway/core/directory-chain
    path: src/lib/iccf
    tagOrBranch: 1.87.0
    rid: x"9C359787B75927733034EA1CEE74EEC8829D2907E4FC94790B5E9ABE4396575D"
  iccf_test:
    registry: https://gitlab.com/chromaway/core/directory-chain
    path: src/lib/test/iccf
    tagOrBranch: 1.87.0
    rid: x"873D71557531E35E453587FA71C2D3CCB674F0EB49D18B30FA838C52C1155EB3"
```

Written for this site from Chromia’s public course. Code samples are the course’s own.

[← Previous**Confirm Events Across Blockchains**](https://chromia.com/learn/iccf-course/introduction/)[Next →**System overview**](https://chromia.com/learn/iccf-course/system-overview/)

On this page

* [Install](#install)
* [Prerequisite](#prerequisite)
* [Installation](#installation)
* [Updating Chromia CLI](#updating-chromia-cli)
* [Docker](#docker)