Skip to main content

Set up your project

Before we start, please make sure you have the following prerequisites in place:

Set up PostgreSQL database

Set up PostgreSQL database

Rell requires PostgreSQL 16.3. The IDE can work without it but can't run a node. A console or a remote postchain app can run without a database.

The default database configuration for Rell is:

  • database: postchain
  • user: postchain
  • password: postchain

Install​

  1. Install Homebrew: Homebrew installation guide

  2. Install PostgreSQL:

    brew install postgresql@16
    brew services start postgresql@16
    createuser -s postgres

  3. Prepare the PostgreSQL database:

    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

    If you get an error saying peer authentication failed, you must change the authentication method from peer to md5. You can change it in the pg_hba.conf file of your psql database.

Install Chromia CLI

Install Chromia CLI

This topic contains instructions to install and update the Chromia CLI.

Prerequisite​

Before proceeding, make sure the following prerequisites are met:

  • PostgreSQL database: See Set up PostgreSQL database.
  • RELL_JAVA environment: Chromia CLI do requries a java runtime (version 21 or later) to execute. Through the different package managers this has been abstracted away for you so you don't need to set this up. If you want to control which java runtime you use to execute Chromia CLI with it is recomended to set RELL_JAVA variable in your environment to point to a valid Java installation

Installation​

You can install Chromia CLI using a package manager or by downloading it directly from Chromia CLI Packages.

To install Chromia CLI (chr) on macOS, follow these steps:

  1. If Homebrew is not installed, install it by running:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Add the Chromia repository to Homebrew by running the following command:

    brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git

  3. Install Chromia CLI with:

    brew install chromia/core/chr
    info

    To install a specific version of Chromia CLI, use the following commands:

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

    You can list available versions using: brew search chr.

  4. To verify the installation, check the version by running:

    chr --version

Updating Chromia CLI​

You can download and install the latest Chromia CLI from here, or if you have installed the Chromia CLI via a package manager, you can update it with the following:

brew update
brew upgrade chr

Docker​

Docker can run a standalone Linux container with the Chromia CLI pre-installed. Make sure that you have set up the PostgreSQL database.

To use the published Docker images, you must first have Docker installed and configured on your host machine. Please refer to the Docker documentation on how to install Docker on Windows, Mac, and Linux.

Start the Docker container with Chromia CLI pre-installed​

To run the latest version of the Chromia CLI, use the docker run command and specify the CLI Docker image name and chr.

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

Make sure to configure your chromia.yml file correctly:

  • Mac: Use host.docker.internal for database:host.
  • Windows: Set database:host to 172.17.0.1.
  • Linux: Use the --network=host argument in Docker commands.

These configurations are crucial to ensure connectivity between Chromia CLI and the PostgreSQL instance.

See the Docker command line reference for more information on updating or uninstalling the Docker image.

#!/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 "$@"

Let's kick things off by setting up your blockchain app project. Follow these steps:

  1. Create a new project from the template using the Chromia CLI:
chr create-rell-dapp order-system-example --template=plain
cd order-system-example
  1. Configure the ICMF library by adding the following to the newly generated chromia.yml file:
chromia.yml
libs:
  icmf:
    registry: https://gitlab.com/chromaway/core/directory-chain
    path: src/messaging/icmf
    tagOrBranch: 1.29.0
    rid: x"19D6BC28D527E6D2239843608486A84F44EDCD244E253616F13D1C65893F35F6"

  1. Run chr install to download the library. This will allow sending and receiving messages between different blockchains.

  2. Add the following definitions to the very beginning of the chromia.yml file that will make it easier for us to configure the chains for messaging:

chromia.yml
definitions:
  - &sender # Configuration for a chain that sends messages
    gtx:
      modules:
        - "net.postchain.d1.icmf.IcmfSenderGTXModule"
  - &receiver # Base configuration for a chain that receives messages
    gtx:
      modules:
        - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
    sync_ext:
      - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
  - &sender_receiver # Base configuration for a chain that will both send and receive messages
    gtx:
      modules:
        - "net.postchain.d1.icmf.IcmfSenderGTXModule"
        - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
    sync_ext:
      - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"

Here we have defined an array containing three elements, each associated with an anchor: &sender, &receiver, and &sender_receiver. Each of these anchors represents a specific configuration that a chain will adopt based on whether it is intended to send messages, receive messages, or both.

Below you can find the project structure and also the contents of the chromia.yml configuration file after the performed changes. It can be very useful for comparison:

Project structure

order-system-example/ 
├── build/ 
├── src/ 
│   ├── lib/ 
│   ├── test/ 
│   └── main.rell 
├── .gitignore 
└── chromia.yml

Final version of the chromia.yml file

chromia.yml
definitions:
  - &sender # Configuration for a chain that sends messages
    gtx:
      modules:
        - "net.postchain.d1.icmf.IcmfSenderGTXModule"
  - &receiver # Base configuration for a chain that receives messages
    gtx:
      modules:
        - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
    sync_ext:
      - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
  - &sender_receiver # Base configuration for a chain that will both send and receive messages
    gtx:
      modules:
        - "net.postchain.d1.icmf.IcmfSenderGTXModule"
        - "net.postchain.d1.icmf.IcmfReceiverGTXModule"
    sync_ext:
      - "net.postchain.d1.icmf.IcmfReceiverSynchronizationInfrastructureExtension"
blockchains:
  order-system-example:
    module: main
compile:
  rellVersion: 0.13.5
database:
  schema: schema_order_system_example
test:
  modules:
    - test
libs:
  icmf:
    registry: https://gitlab.com/chromaway/core/directory-chain
    path: src/messaging/icmf
    tagOrBranch: 1.29.0
    rid: x"19D6BC28D527E6D2239843608486A84F44EDCD244E253616F13D1C65893F35F6"