02 / 06Intermediate

Set up your project

You need the following in place before you begin:

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

Install Homebrew by following the Homebrew setup instructions.

Install PostgreSQL:

shell

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

Create the database and user:

plsql

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;"

Install PostgreSQL:
bash
```
sudo apt install postgresql-16
```

Create the database and user:

bash

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;"

Install Docker by following the Docker setup instructions.
Create the database and user:
dockerfile
```
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
```
POSTGRES_INITDB_ARGS="--lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --encoding=UTF-8"
```

Get the PostgreSQL installer from the PostgreSQL download page.
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
```
setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"
```
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
```
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

The steps below show how to install and update the Chromia CLI.

Prerequisite

Check that you have the following before you continue:

PostgreSQL database: Follow Set up a 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.

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

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

bash

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

bash

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

Install the Chromia CLI:
bash
```
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 chrbrew link chr@<version>
```
Run brew search chr to see which versions are available.
Confirm the installation by printing the version:
bash
```
chr --version
```

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

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

bash

curl -fsSL https://apt.chromia.com/chromia.gpg | sudo tee /usr/share/keyrings/chromia.gpg

Add the Chromia repository to your package sources:

bash

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

Refresh your package sources:
bash
```
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
```
sudo apt-get --allow-releaseinfo-change update
```
After the update completes, install the Chromia CLI:
bash
```
sudo apt-get install chr
```
Confirm the installation by printing the version:
bash
```
chr --version
```

On Windows, install the Chromia CLI (chr) with Scoop as follows:

If you don't have Scoop yet, open PowerShell as Administrator and run:
powershell
```
iwr -useb get.scoop.sh | iex
```

Add the Chromia bucket to Scoop:

powershell

scoop bucket add chromia https://gitlab.com/chromaway/core-tools/scoop-chromia/

Add the Java bucket to Scoop:
powershell
```
scoop bucket add java
```
With this bucket in place, Scoop can download openjdk21, which chromia-cli needs during installation.
Install the Chromia CLI:
powershell
```
scoop install chr
```
Confirm the installation by printing the version:
powershell
```
chr --version
```

Updating Chromia CLI

Download the newest Chromia CLI from the package registry. If you installed it with a package manager, update it with the command for your platform:

shell

brew updatebrew upgrade chr

shell

sudo apt-get updatesudo apt-get install chr

shell

scoop updatescoop 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 set up.

The published images require Docker to be installed and configured on your host. The Docker documentation explains how to 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

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

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

To update or remove the Docker image, consult the Docker CLI reference.

bash

#!/bin/bash# Allocate a pseudo-TTY one when run in interactive modeif [ -t 0 ] && [ -t 1 ] ; then TTY="--tty"; else TTY=""; fidocker 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

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

Start by creating the project for your blockchain app:

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

shell

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

shell

cd digital_warehouse_example

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: maincompile:  rellVersion: 0.14.9database:  schema: schema_digital_warehouse_exampletest:  modules:    - testlibs:  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.