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
- Mac
- Linux
- Docker
-
Install Homebrew: Homebrew installation guide
-
Install PostgreSQL:
brew install postgresql@16
brew services start postgresql@16
createuser -s postgres
- Prepare the PostgreSQL database:
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';" -c "CREATE ROLE postchain LOGIN ENCRYPTED PASSWORD 'postchain'; GRANT ALL ON DATABASE postchain TO postchain;"
If you get an error saying that peer authentication failed, you need to change the authentication method from
peer
tomd5
. You can change it in thepg_hba.conf
file of yourpsql
database.
- Install PostgreSQL:
sudo apt install postgresql-16
- Prepare the PostgreSQL database:
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: Docker installation guide
-
Prepare the PostgreSQL database:
docker run --name postgres -e POSTGRES_USER=postchain -e POSTGRES_PASSWORD=postchain -p 5432:5432 -d postgres:16.3-alpine3.20
We use the Alpine version of PostgreSQL because it provides the correct collation settings by default. This can be explicitly set using the environment variable:
POSTGRES_INITDB_ARGS="--lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --encoding=UTF-8"
Install Chromia CLI
Install Chromia CLI
This topic contains instructions to install and update the Chromia CLI.
Prerequisite
- Install PostgreSQL database; see Set up PostgreSQL database.
Install
Before installing the Chromia CLI, ensure you have installed the Java Development Kit (open JDK) and have at least Java 21. For more information, see JDK installation guide.
You can download and install the latest Chromia CLI from here or via a package manager:
- Mac
- Linux/WSL
- Windows
brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git
brew install chromia/core/chr
Some versions are backed up, so you can return to a previous version of the CLI. To install a prior version, use this command to install and switch versions:
brew install chromia/core/chr@<version>
brew unlink chr
brew link chr@<version>
To see which versions are available, search for them using brew search: brew search chr
.
Download the public key of apt-repo and add it to your local keyrings:
curl -fsSL https://apt.chromia.com/chromia.gpg | sudo tee /usr/share/keyrings/chromia.gpg
Add the repository to your list of package sources:
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
If you have added apt.chromia.com to your list of sources before version 0.16.0 of Chromia CLI, you will need to add the
flag --allow-releaseinfo-change
when running the apt-get update
command to allow apt to update the repository.
sudo apt-get --allow-releaseinfo-change update
Update apt-get and install:
sudo apt-get update
sudo apt-get install chr
You can use Scoop to install the latest Chromia CLI as follows:
scoop bucket add chromia https://gitlab.com/chromaway/core-tools/scoop-chromia/
scoop install chr
Update
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:
- Mac
- Linux
- Windows
brew update
brew upgrade chr
sudo apt-get update
sudo apt-get install chr
scoop update
scoop update 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
When configuring your chromia.yml
file to ensure the Chromia CLI can access the PostgreSQL instance, use the following
instructions based on your operating system:
- Mac: Specify
host.docker.internal
in thedatabase:host
field inchromia.yml
. - Windows: Set
database:host
to172.17.0.1
inchromia.yml
. - Linux: Instead of modifying
chromia.yml
, when running Docker on Linux, include the--network=host
argument in your Docker CLI commands.
These configurations are crucial to ensure connectivity between Chromia CLI and the PostgreSQL instance.
See the Docker command line reference for information about 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 "$@"
We will start by setting up a new project using Chromia CLI.
chr create-rell-dapp fee-strategies --template=plain-multi
cd fee-strategies
To finalize the setup, we add the FT4 library to our project. Open your chromia.yml
file and add ft4
to a new libs
section and configure the public key as the admin key for our dapp:
blockchains:
module: fee
moduleArgs:
lib.ft4.core.admin:
admin_pubkey: "03C8D12D9D3DD97DA5A20A569DA5E25E81C9C8DB44BBDB1BE798D9F1B695420BBD"
compile:
rellVersion: 0.13.5
database:
schema: schema_my_rell_dapp
test:
modules:
- test
moduleArgs:
lib.ft4.core.admin:
admin_pubkey: "03C8D12D9D3DD97DA5A20A569DA5E25E81C9C8DB44BBDB1BE798D9F1B695420BBD"
libs:
ft4:
registry: https://bitbucket.org/chromawallet/ft3-lib
path: rell/src/lib/ft4
tagOrBranch: v0.7.0r
rid: x"F7C207AA595ABD25FDE5C2C2E32ECD3768B480AD03D1F2341548FF4F37D9B7AF"
insecure: false
To install FT4, we run:
chr install
That's the basic setup for using FT4. In the upcoming lessons, we will use this to create assets, transfer tokens, and register user accounts.