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://s3.eu-central-003.backblazeb2.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://s3.eu-central-003.backblazeb2.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://s3.eu-central-003.backblazeb2.com/ricochet-server/${VERSION#v}/ricochet-${VERSION#v}-x86_64.tar.gz

# Or for aarch64
# curl -fLO https://s3.eu-central-003.backblazeb2.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.

Using the standalone binary

The standalone binary can run either as a blocking foreground process or as a daemonized background process.

Foreground mode

By default, ricochet start runs in the foreground and prints logs to stdout/stderr:

ricochet start --config /path/to/ricochet-config.toml

The --config flag specifies the path to your ricochet-config.toml. If omitted, ricochet looks for ricochet-config.toml in the current working directory, so it is recommended to always pass --config with an explicit path.

Tip

Set home to an absolute path in your ricochet-config.toml. This controls where ricochet stores its database, content bundles, and logs. If omitted, it defaults to the current working directory at start time.

Daemon mode

Use --daemon when you want ricochet to keep running after your terminal session ends. This is useful on remote servers where you do not want the process tied to your SSH connection. This is similar to running ricochet through systemd, which is what the .rpm and .deb installers do by default. For production use, the prepackaged installers are recommended over the standalone binary.

Pass --daemon to detach the process and run it in the background:

ricochet start --config /path/to/ricochet-config.toml --daemon

Note

The --daemon flag is only available on Unix-like operating systems.

When running as a daemon, ricochet writes the following files under RICOCHET_HOME:

File	Purpose
ricochet.pid	Process ID of the running daemon
ricochet.stdout	Standard output from the process
ricochet.err	Standard error from the process

ricochet.stdout and ricochet.err capture raw process output such as startup errors, panics, and anything printed before the logging system initializes. They are separate from the structured log files written by the [logs] configuration. For operational logging, configure [logs] in your ricochet-config.toml. See File Logging for configuration options.

Stopping the daemon

Use ricochet stop to gracefully stop a daemonized process:

ricochet stop --config /path/to/ricochet-config.toml

If you passed a custom --config path to ricochet start, pass the same path to ricochet stop so it can locate the correct ricochet.pid file.

Upgrade

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

Debian / Ubuntu

curl -fLO https://s3.eu-central-003.backblazeb2.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://s3.eu-central-003.backblazeb2.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.