Host

ricochet-server is distributed as native Linux packages and standalone binaries. This guide covers manual installation on a single host.

Supported platforms

Distribution	Architecture	Package format
Debian / Ubuntu	amd64, arm64	.deb
AlmaLinux / RHEL / EL	x86_64, aarch64	.rpm
Other Linux	x86_64, aarch64	.tar.gz
macOS	Apple Silicon	.tar.gz
Windows	x86_64, arm64	.zip

Install the package

ricochet-server packages are published to S3 buckets.

Debian / Ubuntu

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
ARCH=$(dpkg --print-architecture)
curl -fLO https://s3.eu-central-003.backblazeb2.com/ricochet-server/${VERSION#v}/ricochet-server_${VERSION#v}-1_${ARCH}.deb
sudo apt install ./ricochet-server_${VERSION#v}-1_${ARCH}.deb

RHEL / AlmaLinux

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
ARCH=$(uname -m)
curl -fLO https://s3.eu-central-003.backblazeb2.com/ricochet-server/${VERSION#v}/ricochet-server-${VERSION#v}-1.el10.${ARCH}.rpm
sudo dnf install ./ricochet-server-${VERSION#v}-1.el10.${ARCH}.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 as ricochet
tar -xzf ricochet-${VERSION#v}-*.tar.gz
chmod +x ricochet-server
sudo mv ricochet-server /usr/local/bin/ricochet

The .deb and .rpm packages install the ricochet binary and a ricochet-server.service systemd unit.

Configure

In packaged .rpm and .deb installations of ricochet, the configuration file is stored at /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 0600 /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.

Linux prerequisites

The .deb and .rpm packages configure these prerequisites automatically. Complete these steps only when installing the standalone binary.

Install newuidmap and newgidmap:

Debian / Ubuntu

sudo apt update
sudo apt install uidmap

RHEL / AlmaLinux

sudo dnf install shadow-utils-subid

Grant the account that runs ricochet at least 65,536 subordinate user and group IDs. The following example configures root, which is the account used by the packaged systemd service. Choose an unused range if 100000-165535 is already allocated in /etc/subuid or /etc/subgid:

sudo usermod --add-subuids 100000-165535 root
sudo usermod --add-subgids 100000-165535 root

On Ubuntu 23.10 and later, create and load an AppArmor profile that permits ricochet to create unprivileged user namespaces:

sudo ricochet setup-apparmor

Verify that user namespaces, subordinate ID mappings, and AppArmor are configured for the account that will run ricochet:

sudo ricochet check-security

Foreground mode

By default, ricochet start runs in the foreground and prints logs to stdout and 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

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
ARCH=$(dpkg --print-architecture)
curl -fLO https://s3.eu-central-003.backblazeb2.com/ricochet-server/${VERSION#v}/ricochet-server_${VERSION#v}-1_${ARCH}.deb
sudo apt install ./ricochet-server_${VERSION#v}-1_${ARCH}.deb
sudo systemctl restart ricochet-server.service

RHEL / AlmaLinux

VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
ARCH=$(uname -m)
curl -fLO https://s3.eu-central-003.backblazeb2.com/ricochet-server/${VERSION#v}/ricochet-server-${VERSION#v}-1.el10.${ARCH}.rpm
sudo dnf install ./ricochet-server-${VERSION#v}-1.el10.${ARCH}.rpm
sudo systemctl restart ricochet-server.service

Note

Use dnf install instead of dnf upgrade because it handles fresh installs, upgrades, and downgrades.

macOS

ricochet-server is distributed as a standalone binary for Apple Silicon Macs. Intel Macs are not supported.

Download and install the latest release:

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-${VERSION#v}-aarch64-macos.tar.gz
tar -xzf ricochet-${VERSION#v}-aarch64-macos.tar.gz
chmod +x ricochet-server
sudo mv ricochet-server /usr/local/bin/ricochet-server

Keep the ricochet-server name so that the server does not shadow the ricochet CLI, which is commonly installed on the same machine.

Create a configuration file as described in Configure, set home to an absolute writable path, and start the server in the foreground:

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

The macOS binary does not include a service definition or vendored language dependencies. Install uv, juliaup, and renv separately when you need the corresponding runtimes.

Windows

ricochet-server is distributed as a standalone executable for x86_64 and arm64 Windows. Run these commands in PowerShell, replacing x86_64 with aarch64 on Windows arm64:

$Version = (Invoke-RestMethod https://ricochet.rs/releases.json).latest.TrimStart("v")
Invoke-WebRequest "https://s3.eu-central-003.backblazeb2.com/ricochet-server/$Version/ricochet-$Version-x86_64-windows.zip" -OutFile "ricochet-$Version-x86_64-windows.zip"
Expand-Archive "ricochet-$Version-x86_64-windows.zip" -DestinationPath . -Force
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\Ricochet" | Out-Null
Move-Item .\ricochet-server.exe "$env:LOCALAPPDATA\Programs\Ricochet\ricochet-server.exe" -Force

Keep the ricochet-server.exe name so that the server does not shadow the ricochet CLI, which is commonly installed on the same machine.

Add %LOCALAPPDATA%\Programs\Ricochet to your user PATH, then create a configuration file as described in Configure. Set home to an absolute writable Windows path.

Start the server in the foreground:

ricochet-server start --config C:\path\to\ricochet-config.toml

Windows does not support ricochet-server start --daemon or ricochet-server stop. Stop the foreground server with Ctrl+C, or configure it with a Windows service manager. The Windows binary does not include vendored language dependencies.

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.