Overview

You configure ricochet with a ricochet-config.toml file. This file sets OIDC login, the default user role, the execution backend, and item storage.

With the default ricochet systemd service, the file lives at /var/lib/ricochet/ricochet-config.toml. With the ricochet server CLI, pass the file with ricochet start --config /path/to/ricochet-config.toml.

Tip

If no config file exists, ricochet creates one the first time it starts.

Example ricochet-config.toml

home = "/var/lib/ricochet/data"

[auth]
default_role = "developer"
require_authentication = false  # Set to true to require login for all access

[auth.oidc]
issuer_url = "https://auth.example.com"
client_id = "your-client-id"
client_secret = "your-client-secret"
redirect_url = "http://localhost:6188/oauth/callback"

Storage

ricochet needs persistent storage for its database, deployments, and encryption keys. This location is called RICOCHET_HOME.

• Directorycontent/ deployment bundles

  • …
• .ricochet.json encryption keys
• .ricochet.pub public rsa key
• ricochet.sqlite3 ricochet’s database

By default, RICOCHET_HOME is the current working directory. To change it, set the top-level home key in ricochet-config.toml, such as home = "/path/to/ricochet/home". You can also set it with an environment variable. For the systemd service, the default is /var/lib/ricochet/data.

Tip

With the standalone binary, set home to an absolute path in your ricochet-config.toml. ricochet then uses the same home no matter which folder you start it from.

Or set the RICOCHET_HOME environment variable to the home path you want.

ricochet uses hybrid encryption to keep environment variables and credentials safe. It stores the keys at RICOCHET_HOME/.ricochet.json and RICOCHET_HOME/.ricochet.pub. To read or write the keys in another place, set the secrets field in ricochet-config.toml. This helps most with the Kubernetes backend. See Encryption keys for details.

Environment Variables

Environment variables override TOML settings. Use the RICOCHET_ prefix, and use double underscores (__) for nested keys. For example, these variables set values in [auth] and [auth.oidc]:

RICOCHET_AUTH__OIDC__CLIENT_SECRET=secret-value
RICOCHET_AUTH__DEFAULT_ROLE=consumer
RICOCHET_AUTH__REQUIRE_AUTHENTICATION=false

Configuration Precedence

ricochet applies config values in this order:

1. Environment variables win over ricochet-config.toml
2. ricochet-config.toml wins over default values

Configuration settings

AuthenticationConfigure OIDC authentication with your identity provider.

User RolesConfigure default user roles and understand ricochet's permission system.

Package RepositoriesOverride default package sources for R and Python content items.

Execution BackendUse Kubernetes, Docker, or Podman as an execution backend.