Host

Ricochet Server is distributed as native .deb and .rpm packages and runs as a systemd service. This guide covers manual installation on a single Linux server.

Supported platforms

Distribution	Architecture	Package format
Debian / Ubuntu	amd64	.deb
AlmaLinux / RHEL / EL	x86_64	.rpm

Install the package

Ricochet Server packages are published to object storage.

Debian / Ubuntu

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
curl -fLO https://hel1.your-objectstorage.com/ricochet-server/${VERSION#v}/ricochet-server_${VERSION#v}-1_amd64.deb
sudo apt install ./ricochet-server_${VERSION#v}-1_amd64.deb

RHEL / AlmaLinux

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
curl -fLO https://hel1.your-objectstorage.com/ricochet-server/${VERSION#v}/ricochet-server-${VERSION#v}-1.el10.x86_64.rpm
sudo dnf install ./ricochet-server-${VERSION#v}-1.el10.x86_64.rpm

Standalone binary

We also provide universal statically linked linux binaries which are available for x86_64 and aarch64. These can be used for operating systems that we do not officially support.

Note

The standalone binary does not include systemd service configuration. You will need to manage the process manually or create your own service file.

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
# For x86_64
curl -fLO https://hel1.your-objectstorage.com/ricochet-server/${VERSION#v}/ricochet-${VERSION#v}-x86_64.tar.gz

# Or for aarch64
# curl -fLO https://hel1.your-objectstorage.com/ricochet-server/${VERSION#v}/ricochet-${VERSION#v}-aarch64.tar.gz

# Extract and install
tar -xzf ricochet-${VERSION#v}-*.tar.gz
chmod +x ricochet
sudo mv ricochet /usr/local/bin/

The package installs the ricochet binary and a ricochet-server.service systemd unit.

Configure

Ricochet reads its configuration from /var/lib/ricochet/ricochet-config.toml.
Create or edit this file with your deployment’s settings.

At a minimum you need to configure OIDC authentication:

/var/lib/ricochet/ricochet-config.toml

[auth.oidc]
issuer_url = "https://your-idp.example.com/"
client_id = "your-client-id"
client_secret = "your-client-secret"
redirect_url = "https://your-ricochet-host.example.com/oauth/callback"

Ensure appropriate permissions are set on the config file:

sudo chmod 0644 /var/lib/ricochet/ricochet-config.toml
sudo chown root:root /var/lib/ricochet/ricochet-config.toml

Caution

The config file contains your OIDC client secret. Restrict read access as appropriate for your environment.

Start the service

1. Reload systemd to pick up the new unit file:

   sudo systemctl daemon-reload

2. Enable and start the service:

   sudo systemctl enable --now ricochet-server.service

3. Verify the service is running:

   sudo systemctl status ricochet-server.service

Ricochet Server listens on port 6188 by default.

Upgrade

To upgrade to a new version, download the new package and install it over the existing one.

Debian / Ubuntu

curl -fLO https://hel1.your-objectstorage.com/ricochet-server/${VERSION}/ricochet-server_${VERSION}-1_amd64.deb
sudo apt install ./ricochet-server_${VERSION}-1_amd64.deb
sudo systemctl restart ricochet-server.service

RHEL / AlmaLinux

curl -fLO https://hel1.your-objectstorage.com/ricochet-server/${VERSION}/ricochet-server-${VERSION}-1.el10.x86_64.rpm
sudo dnf install ./ricochet-server-${VERSION}-1.el10.x86_64.rpm
sudo systemctl restart ricochet-server.service

Note

Use dnf install (not dnf upgrade) — it handles both fresh installs and version changes, including downgrades.

Data science interpreters

Ricochet works without any interpreters installed. However, if you plan to deploy R, Python, or Julia content, you must install the respective interpreters on the host machine. Container and Kubernetes deployments bundle their own interpreters and do not require this step.

Vendored dependencies

The .deb and .rpm packages bundle the following tools so that ricochet can manage language environments without relying on system-installed versions:

Tool	Vendor path	Purpose
uv	RICOCHET_HOME/vendor/py/uv	Python package management, running Python content, and Python version discovery
juliaup	RICOCHET_HOME/vendor/jl/juliaup	Managing Julia environments and Julia version discovery
renv	RICOCHET_HOME/vendor/r/renv	R package environment restoration

When using the systemd service, RICOCHET_HOME defaults to /var/lib/ricochet/data. See the storage configuration for more details.

Note

The standalone binary does not include vendored dependencies. You must install uv, juliaup, and renv yourself if using the standalone binary.

Python

If deploying Python-based content, Ricochet will discover Python installations on the host. We encourage installing Python via uv for the best experience managing multiple Python versions.

uv python install <version>

R

We recommend using rig to install R:

rig add <version>

You can also install R from CRAN or your distribution’s package manager. However, if you want to make use of multiple R versions, rig is the easiest and most flexible option.

Julia

If deploying Julia-based content, Ricochet uses juliaup to discover installed Julia channels. Julia must be installed via juliaup. Only juliaup-managed Julia installations are supported.

juliaup add <version>

Ansible

If you manage your infrastructure with Ansible, the devxy.data_science_core collection provides roles for installing R, Python, and their system dependencies:

ansible-galaxy collection install devxy.data_science_core

roles:
  - role: devxy.data_science_core.r
  - role: devxy.data_science_core.python

System libraries

The interpreters may require additional system libraries for compiling packages at runtime.
Here’s a baseline of system libraries which we recommend installing:

Debian / Ubuntu

sudo apt install \
  libgit2-dev libxml2-dev libharfbuzz-dev libfreetype-dev libfontconfig-dev \
  libgdal-dev libproj-dev libgeos-dev libjq-dev libmagick++-dev \
  libnetcdf-dev libfribidi-dev jags libglpk-dev libpng-dev \
  libsecret-1-dev poppler-utils libreadline-dev unixodbc-dev \
  default-jdk-headless libicu-dev libudunits2-dev libsodium-dev \
  zlib1g-dev libglu1-mesa-dev libcairo2-dev git freetds-common \
  libv8-dev librsvg2-dev libsqlite3-dev libpq-dev libgmp3-dev libmpfr-dev

RHEL / AlmaLinux

sudo dnf install \
  libgit2-devel libxml2-devel harfbuzz-devel freetype-devel fontconfig-devel \
  gdal-devel proj-devel geos-devel jq-devel ImageMagick-c++-devel \
  netcdf-devel fribidi-devel glpk-devel libpng-devel \
  libsecret-devel poppler-utils readline-devel unixODBC-devel \
  java-21-openjdk-headless libicu-devel udunits2-devel libsodium-devel \
  zlib-devel mesa-libGLU-devel cairo-devel git freetds \
  librsvg2-devel sqlite-devel libpq-devel gmp-devel mpfr-devel

Uninstall

Debian / Ubuntu

sudo systemctl stop ricochet-server.service
sudo systemctl disable ricochet-server.service
sudo apt purge ricochet-server

RHEL / AlmaLinux

sudo systemctl stop ricochet-server.service
sudo systemctl disable ricochet-server.service
sudo dnf remove ricochet-server

The configuration file at /var/lib/ricochet/ricochet-config.toml is not removed automatically. Delete it manually if it is no longer needed.