Skip to main content

Install Chromia CLI

This guide provides detailed instructions for installing and updating the Chromia CLI.

Prerequisites​

Before installing Chromia CLI, ensure the following requirements are met:

  • PostgreSQL Database: Refer to the Set up PostgreSQL database.
  • Java Runtime (RELL_JAVA): Chromia CLI requires Java Runtime Environment (version 21 or later). Package managers handle this automatically. To control the Java runtime explicitly, set the RELL_JAVA environment variable to a valid Java installation path.

Using Docker is the recommended way to install Chromia CLI as it provides an isolated environment with Chromia CLI pre-installed. Make sure you have Docker installed and configured on your machine.

Install 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. Follow the Docker installation guide to install Docker on your system.

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
info

This prefix is required for all chr commands, not just during setup. This ensures that the chr commands run inside the Docker container correctly and can access your project files.

Example:

docker run --rm -v "$(pwd):/usr/app" registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:0.22.2 chr test

Docker database configuration​

Configure your chromia.yml file based on your operating system:

Operating systemDatabase host configuration
macOSSet database:host to host.docker.internal
WindowsSet database:host to 172.17.0.1
LinuxUse --network=host in the Docker run command

Advanced Docker configuration​

You can customize the Docker command further using this script:

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

This script mounts the current directory into the container and ensures that Chromia CLI runs with the correct user and environment settings.

For additional details, refer to the Docker documentation.

Installation via package managers (optional)​

If you prefer not to use Docker, Chromia CLI can also be installed using package managers.

To install Chromia CLI (chr) on macOS, follow these steps:

  1. Install Homebrew (if not already installed):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Add the Chromia repository to Homebrew:

    brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git

  3. Install Chromia CLI:

    brew install chromia/core/chr
    info

    To 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.

  4. Verify the installation:

    chr --version

Updating Chromia CLI​

You can download and install the latest Chromia CLI from here, or update via package managers:

brew update
brew upgrade chr