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
- Windows
-
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 = '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;"
noteIf you get an error saying peer authentication failed, you must 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
noteWe 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"
-
Download the PostgreSQL installer from the official website.
-
Install the executable and add the PostgreSQL folder containing the binaries to your environment variables. Open the Command Prompt (CMD) and run the following command, ensuring that you set the path to your binaries correctly and replace the
<version>
placeholder with the actual version number:setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"
-
Reopen the Command Prompt (CMD) to update the environment variables. Prepare the PostgreSQL database by running the following two commands sequentially:
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;"noteDepending on your Windows version, you may encounter various errors related to permissions or incorrect PostgreSQL installations. If this happens, we recommend installing Docker and deploying the PostgreSQL container.
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.
- macOS
- Linux/WSL
- Windows
To install Chromia CLI (chr
) on macOS, follow these steps:
-
If Homebrew is not installed, install it by running:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-
Add the Chromia repository to Homebrew by running the following command:
brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git
-
Install Chromia CLI with:
brew install chromia/core/chr
infoTo 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
. -
To verify the installation, check the version by running:
chr --version
To install Chromia CLI (chr
) on Linux or WSL (Windows Subsystem for Linux), follow these steps:
-
Download and add Chromia's
apt-repo
public key to your system’s trusted keyrings:curl -fsSL https://apt.chromia.com/chromia.gpg | sudo tee /usr/share/keyrings/chromia.gpg
-
Add the Chromia 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
-
Run the following command to update your package sources:
sudo apt-get update
infoIf you added
apt.chromia.com
before Chromia CLI version0.16.0
, run the following command to allow the repository update:sudo apt-get --allow-releaseinfo-change update
-
Once the repository is updated, install Chromia CLI by running:
sudo apt-get install chr
-
To verify that Chromia CLI is installed successfully, check the version:
chr --version
To install Chromia CLI (chr
) on Windows using Scoop, follow these steps:
-
If Scoop is not installed, install it by running the following command in PowerShell (run as Administrator):
iwr -useb get.scoop.sh | iex
-
Add the Chromia repository (bucket) to Scoop by running:
scoop bucket add chromia https://gitlab.com/chromaway/core-tools/scoop-chromia/
-
Add the Java bucket to Scoop by running:
scoop bucket add java
This will enable scoop to download the openjdk21 which chromia-cli depends on when installing
-
Install Chromia CLI by running:
scoop install chr
-
To verify that Chromia CLI is installed successfully, check the version:
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:
- macOS
- 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
Make sure to configure your chromia.yml
file correctly:
- Mac: Use
host.docker.internal
fordatabase:host
. - Windows: Set
database:host
to172.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. Clone the Tic Tac Toe game repository:
git clone git@bitbucket.org:chromawallet/demo-unity.git
Navigate to the Tic Tac Toe project directory:
cd tic-tac-toe
Install the necessary libraries:
chr install