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 using the Chromia CLI.

chr create-rell-dapp book-review --template=plain
cd book-review

This command will generate essential project files and configurations for you.