# Set up your project · Build a chat agent on Chromia · Learn Chromia

> Rell needs PostgreSQL 16.3. You can use the IDE without a database, but you won't be able to run a node. Running a console or a remote postchain app doesn't…

Source: https://chromia.com/learn/chat-agent-course/setup/

Build a chat agent on ChromiaLesson 2 of 5

1. [01Build a chat agent on Chromia](https://chromia.com/learn/chat-agent-course/introduction/)
2. [02Set up your project](https://chromia.com/learn/chat-agent-course/setup/)
3. [03Configure your API key](https://chromia.com/learn/chat-agent-course/configure-api-key/)
4. [04Test your setup](https://chromia.com/learn/chat-agent-course/test-your-setup/)
5. [05Explore and extend](https://chromia.com/learn/chat-agent-course/explore-and-extend/)

[Learn](https://chromia.com/learn/)[Build a chat agent on Chromia](https://chromia.com/learn/chat-agent-course/)

02 / 05Advanced

# Set up your project

Before you begin, install the following:

Set up PostgreSQL database

## 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. Running a console or a remote postchain app doesn't need a database.

By default, Rell expects this database configuration:

* database: `postchain`
* user: `postchain`
* password: `postchain`

## Install

1. Install Homebrew by following the [Homebrew installation guide](https://brew.sh/).
2. Install PostgreSQL:

   shell

   ```
   brew install postgresql@16
   brew services start postgresql@16
   createuser -s postgres
   ```
3. Create and configure the database:

   plsql

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

   note

   A "peer authentication failed" error means you need to switch the authentication method from `peer` to `md5`. Make this change in the `pg_hba.conf` file of your `psql` database.

1. Install PostgreSQL:

   bash

   ```nolines
   sudo apt install postgresql-16
   ```
2. Create and configure the database:

   bash

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

1. Install Docker by following the [Docker installation guide](https://docs.docker.com/engine/install/).
2. Create and configure the database:

   dockerfile

   ```nolines
   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 them explicitly with this environment variable:

   bash

   ```nolines
   POSTGRES_INITDB_ARGS="--lc-collate=C.UTF-8 --lc-ctype=C.UTF-8 --encoding=UTF-8"
   ```

1. Get the PostgreSQL installer from the [PostgreSQL website](https://www.postgresql.org/download/windows/).
2. 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 your actual binaries path and substitute the real version number for the `<version>` placeholder:

   shell

   ```nolines
   setx POSTGRESQL "C:\Program Files\PostgreSQL\<version>\bin"
   ```
3. Close and reopen 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

   ```nolines
   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

## Install Chromia CLI

Follow these steps to install and update the [Chromia CLI](https://gitlab.com/chromaway/core-tools/chromia-cli).

## Prerequisite

You need the following before you start:

* **PostgreSQL database**: Follow [Set up PostgreSQL database](https://docs.chromia.com/get-started/installation/#set-up-postgresql-database).
* **RELL\_JAVA environment**: Chromia CLI runs on a Java runtime, version 21 or later. The package managers handle this dependency for you, so no manual setup is needed. To choose which Java runtime Chromia CLI uses, 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](https://gitlab.com/chromaway/core-tools/chromia-cli/-/packages).

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

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

   bash

   ```nolines
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
2. Add the Chromia repository to Homebrew:

   bash

   ```nolines
   brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git
   ```
3. Install Chromia CLI:

   bash

   ```nolines
   brew install chromia/core/chr
   ```

   info

   To install a particular version of Chromia CLI, run:

   shell

   ```
   brew install chromia/core/chr@<version>
   brew unlink chr
   brew link chr@<version>
   ```

   To see which versions are available, run `brew search chr`.
4. Confirm the installation by printing the version:

   bash

   ```nolines
   chr --version
   ```

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

1. Download Chromia's `apt-repo` public key and add it to your trusted keyrings:

   bash

   ```nolines
   curl -fsSL https://apt.chromia.com/chromia.gpg | sudo tee /usr/share/keyrings/chromia.gpg
   ```
2. Register the Chromia repository as a package source:

   bash

   ```nolines
   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
   ```
3. Refresh your package sources:

   bash

   ```nolines
   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 be updated:

   bash

   ```nolines
   sudo apt-get --allow-releaseinfo-change update
   ```
4. After the update finishes, install Chromia CLI:

   bash

   ```nolines
   sudo apt-get install chr
   ```
5. Confirm the installation by printing the version:

   bash

   ```nolines
   chr --version
   ```

On Windows, install Chromia CLI (`chr`) with [Scoop](https://scoop.sh/) as follows:

1. If you don't have Scoop yet, install it by running this in PowerShell as Administrator:

   powershell

   ```nolines
   iwr -useb get.scoop.sh | iex
   ```
2. Add the Chromia repository (bucket) to Scoop:

   powershell

   ```nolines
   scoop bucket add chromia https://gitlab.com/chromaway/core-tools/scoop-chromia/
   ```
3. Add the Java bucket to Scoop:

   powershell

   ```nolines
   scoop bucket add java
   ```

   With this bucket in place, Scoop can fetch openjdk21, which chromia-cli needs during installation.
4. Install Chromia CLI:

   powershell

   ```nolines
   scoop install chr
   ```
5. Confirm the installation by printing the version:

   powershell

   ```nolines
   chr --version
   ```

## Updating Chromia CLI

Either download the newest Chromia CLI from the [packages page](https://gitlab.com/chromaway/core-tools/chromia-cli/-/packages), or, if you installed it with a package manager, update it with the command for your platform:

shell

```nolines
brew update
brew upgrade chr
```

shell

```nolines
sudo apt-get update
sudo apt-get install chr
```

shell

```nolines
scoop update
scoop update chr
```

## Docker

You can also run Chromia CLI inside a standalone Linux container where it comes pre-installed. You still need the [PostgreSQL database](https://docs.chromia.com/get-started/installation/#set-up-postgresql-database) set up.

The published Docker images require Docker to be installed and configured on your host. For Windows, Mac, and Linux instructions, see the Docker guide on how to [install Docker](https://docs.docker.com/get-docker/).

### 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

```nolines
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) doesn't understand the `$(pwd)` syntax. Use one of these instead:

* **PowerShell**: `$(Get-Location)` or `$(pwd)`
* **Command Prompt**: `%CD%`

**Command Prompt example:**

cmd

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

note

Set up your `chromia.yml` file for your platform:

* **Mac**: set `database:host` to `host.docker.internal`.
* **Windows**: set `database:host` to `host.docker.internal` (Docker Desktop). If the node still cannot reach your database, try `172.17.0.1`, the default Docker bridge address on Linux.
* **Linux**: pass `--network=host` to your Docker commands.

Without these settings, Chromia CLI can't reach the PostgreSQL instance.

To update or remove the Docker image, consult the [Docker CLI reference](https://docs.docker.com/engine/reference/commandline/docker/).

bash

```
#!/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 "$@"
```

Windows Command Prompt Users

The bash script above relies on `$(pwd)`, which Windows Command Prompt doesn't support. On Windows:

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

**Mount line adjusted for Command Prompt:**

cmd

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

## Clone the repository

Get a local copy of the course repository:

shell

```nolines
git clone https://bitbucket.org/chromawallet/chat-agent-course.git
```

## Navigate to the project directory

Change into the project folder:

shell

```nolines
cd chat-agent-course
```

## Install the necessary libraries

shell

```nolines
npm install
```

If `npm install` fails, try [Bun](https://bun.sh/) instead:

shell

```nolines
bun install
```

To install Bun, see the [Bun installation instructions](https://bun.com/docs/installation/).

Your environment is now set up for the course.

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

[← Previous**Build a chat agent on Chromia**](https://chromia.com/learn/chat-agent-course/introduction/)[Next →**Configure your API key**](https://chromia.com/learn/chat-agent-course/configure-api-key/)

On this page

* [Install](#install)
* [Prerequisite](#prerequisite)
* [Installation](#installation)
* [Updating Chromia CLI](#updating-chromia-cli)
* [Docker](#docker)
* [Clone the repository](#clone-the-repository)
* [Navigate to the project directory](#navigate-to-the-project-directory)
* [Install the necessary libraries](#install-the-necessary-libraries)