02 / 05Advanced

Set up your project

Have the following prerequisites ready before you begin:

Set up PostgreSQL database

Rell needs PostgreSQL 16.3. Without it, the IDE still works, but you can't run a node. A console or a remote postchain app does not need a database.

By default, Rell expects this database configuration:

database: postchain
user: postchain
password: postchain

Install

Get Homebrew by following the Homebrew installation guide.

Install PostgreSQL:

shell

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

Set up the PostgreSQL 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
```

Set up the PostgreSQL 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;"

Get Docker by following the Docker installation guide.
Set up the PostgreSQL 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 Command Prompt (CMD), run the command below. Point it at the correct binaries path and substitute the actual version number for the <version> placeholder:
shell
```
setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"
```
Close and reopen Command Prompt (CMD) so it picks up the new environment variables. Then run these two commands, one after the other, to set up the PostgreSQL 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 problems caused by a faulty PostgreSQL installation. If you run into these, install Docker and run PostgreSQL as a container instead.

Install Chromia CLI

Follow these steps to install and update the Chromia CLI.

Prerequisite

Check that you have the following in place first:

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 needed. To choose which Java runtime runs Chromia CLI, set the RELL_JAVA environment variable to a valid Java installation.

Installation

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

On macOS, install 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 Chromia CLI:
bash
```
brew install chromia/core/chr
```
info
To pin a specific Chromia CLI version, run:
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 Chromia CLI (chr) as follows:

Fetch the public key for Chromia's apt-repo and add it to your system's 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 apt.chromia.com was added on your system before Chromia CLI version 0.16.0, run this command so the repository update is permitted:
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:

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

Add the Chromia bucket (repository) 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 fetch openjdk21, which chromia-cli requires, during installation.
Install Chromia CLI:
powershell
```
scoop install chr
```
Confirm the installation by printing the version:
powershell
```
chr --version
```

Updating Chromia CLI

Get the newest Chromia CLI from the Chromia CLI packages page. If you installed it through a package manager, update it with the matching command:

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 Chromia CLI. You still need a PostgreSQL database set up.

The published Docker images require Docker to be installed and configured on your host. The Docker documentation explains how to install Docker on Windows, Mac, and Linux.

Start the Docker container with Chromia CLI pre-installed

Run the latest Chromia CLI by passing the CLI Docker image name and chr to the docker run command.

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

For details on updating or removing the Docker image, see 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 does not support. On Windows:

PowerShell: run the command unchanged; PowerShell also understands $(pwd)
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 fee_strategies --template=plain-multi

shell

cd fee_strategies

Next, generate a new admin keypair:

shell

chr keygen --file .chromia/admin-keypair

Finally, add the FT4 library to the project. In your chromia.yml file, create a libs section, add ft4 to it, and set the public key as your dapp's admin key:

chromia.yml

blockchains:  fee_strategies:    module: main    moduleArgs:      lib.ft4.core.admin:        admin_pubkey: x"<dapp_account_pubkey>" # Replace with previously generated public key here.compile:  rellVersion: 0.14.9database:  schema: schema_fee_strategiestest:  modules:    - fee_strategies_test  moduleArgs:    lib.ft4.core.admin:        admin_pubkey: x"<dapp_account_pubkey>" # Replace with previously generated public key here.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 FT4 with:

shell

chr install

Your project is now set up for FT4. The following lessons build on it to create assets, transfer tokens, and register user accounts.

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