02 / 06Advanced

Project setup and configuration

Make sure the following prerequisites are in place before you begin:

Set up PostgreSQL database

Rell needs PostgreSQL 16.3. You can use the IDE without a database, but you won't be able to run a node with it. A console or a remote postchain app also runs without a database.

By default, Rell expects this database configuration:

database: postchain
user: postchain
password: postchain

Install

Set up Homebrew by following the Homebrew installation guide.

Install PostgreSQL:

shell

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

Create and configure the database:

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 and configure the database:

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

Set up Docker by following the Docker installation guide.
Create and configure the database:
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 the Command Prompt (CMD), run the command below. Check that the path points to your binaries and substitute the real version number for the <version> placeholder:
shell
```
setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"
```
Close and reopen the Command Prompt (CMD) so the new environment variables take effect. Then run these two commands, one after the other, to create and configure the database:
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
Some Windows versions produce permission errors or end up with a broken PostgreSQL installation. If you run into this, install Docker and run PostgreSQL as a container instead.

Install Chromia CLI

Follow these steps to install and update the Chromia CLI.

Prerequisite

You need the following before you start:

PostgreSQL database: Follow Set up PostgreSQL database.
RELL_JAVA environment: Chromia CLI runs on a Java runtime, version 21 or later. The package managers handle this for you, so no manual setup is required. To choose which Java runtime runs Chromia CLI, set the RELL_JAVA environment variable to the location of a valid Java installation.

Installation

Install Chromia CLI through a package manager, or download it from Chromia CLI Packages.

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

Install Homebrew if you don't have it yet:

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 Chromia CLI:
bash
```
brew install chromia/core/chr
```
info
To pin a particular version of Chromia CLI, run:
shell
```
brew install chromia/core/chr@<version>brew unlink chrbrew link chr@<version>
```
To see which versions exist, run brew search chr.
Confirm the installation by printing the version:
bash
```
chr --version
```

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

Download Chromia's apt-repo public key 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 set up apt.chromia.com before Chromia CLI version 0.16.0, run this command so the repository can be updated:
bash
```
sudo apt-get --allow-releaseinfo-change update
```
After the update completes, install Chromia CLI:
bash
```
sudo apt-get install chr
```
Confirm the installation by printing the version:
bash
```
chr --version
```

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

Install Scoop if you don't have it yet. Run this in PowerShell as Administrator:
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 available, Scoop can fetch openjdk21, which chromia-cli needs, during installation.
Install Chromia CLI:
powershell
```
scoop install chr
```
Confirm the installation by printing the version:
powershell
```
chr --version
```

Updating Chromia CLI

To get the newest Chromia CLI, download it from the packages page. If you installed it through 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 the PostgreSQL database set up.

The published images require Docker to be installed and configured on your host. For Windows, Mac, and Linux instructions, see install Docker in the Docker documentation.

Start the Docker container with Chromia CLI pre-installed

Run the latest Chromia CLI by passing the CLI image name and chr to docker run:

shell

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

Windows Command Prompt Users

The $(pwd) syntax doesn't work in Windows Command Prompt (cmd). 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 uninstall the Docker image, consult the Docker command line 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 doesn't support. On Windows:

PowerShell: run the script unchanged
Command Prompt: swap $(pwd) for %CD% in the mount command

Mount line adjusted for Command Prompt:

cmd

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

First, create a new project with Chromia CLI.

shell

chr create-rell-dapp asset_management

shell

cd asset_management

Remove src/main.rell together with its test file src/test/data_test.rell. In their place, add a folder named main under src.

Add these files to src/main:

module.rell
entities.rell
functions.rell
operations.rell
queries.rell

Splitting code into files by purpose is standard practice and keeps the project easy to read.

Put the following in src/main/module.rell:

src/main/module.rell

module;

Next, generate an admin keypair:

shell

chr keygen --file .chromia/admin_keypair

Any operation guarded by admin.require_admin(); is authorized with this keypair.

Finish the setup in your chromia.yml file:

list the dependencies in a new libs section
set the admin_pubkey for the dapp. You can read the key with cat .chromia/admin_keypair.

chromia.yml

blockchains:  asset_management:    module: main    moduleArgs:      lib.ft4.core.admin:        admin_pubkey: x"---YOUR_ADMIN_PUBKEY---"compile:  rellVersion: 0.14.8database:  schema: schema_asset_managementtest:  modules:    - test  moduleArgs:    lib.ft4.core.admin:      admin_pubkey: x"033112FB1F0DF70D1EF4098E2F5F7DCB79BB9AD1570513F6CBDF6F9F4EDAC63771"libs:  ft4:    registry: https://gitlab.com/chromaway/ft4-lib.git    path: rell/src/lib/ft4    tagOrBranch: v1.2.0r    rid: x"E96915FD7C9A5DD4E183D86F4A5B4BB5083A7CC1EDEB1465EDFFC926E67C93F6"    insecure: false  iccf:    registry: https://gitlab.com/chromaway/core/directory-chain    path: src/lib/iccf    tagOrBranch: 1.87.0    rid: x"9C359787B75927733034EA1CEE74EEC8829D2907E4FC94790B5E9ABE4396575D"    insecure: false

Install the dependencies with:

shell

chr install

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