Skip to content
ricochet

Container

This page documents how to run ricochet in a Docker container.

  • For multi-node setups, use the Kubernetes installation instead of a standalone container.
  • The container backend is for ricochet-server running on the host next to a container daemon, not for ricochet-server in a container.

We provide standard images for Ubuntu and Alpine variants.

reg.ricochet.rs/ricochet/ricochet-server:<tag>
Variant Base Tag suffix
Ubuntu Ubuntu -ubuntu
Alpine Alpine -alpine

Each release publishes a full version tag plus moving minor and major tags, with and without the OS-variant suffix.

reg.ricochet.rs/ricochet/ricochet-server:<major>.<minor>.<patch>-ubuntu
reg.ricochet.rs/ricochet/ricochet-server:<major>.<minor>-ubuntu
reg.ricochet.rs/ricochet/ricochet-server:<major>-ubuntu

We recommend pinning to a full version tag in production environments. There is no latest tag.

Every ricochet install requires a ricochet-config.toml configuration file. At minimum, configure OIDC authentication:

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"

Mount the ricochet-config.toml alongside the data volume and run:

Terminal window
VERSION=$(curl -s https://ricochet.rs/releases.json | grep -o '"latest": *"[^"]*"' | grep -o 'v[0-9.]*')
docker volume create ricochet-data
docker run -d \
--name ricochet-server \
-p 6188:6188 \
-v ricochet-data:/var/lib/ricochet/data \
-v $(pwd)/ricochet-config.toml:/var/lib/ricochet/data/ricochet-config.toml \
--cap-drop=ALL \
--cap-add=SYS_ADMIN \
--cap-add=SETUID \
--cap-add=SETGID \
--cap-add=DAC_OVERRIDE \
--security-opt seccomp=unconfined \
--security-opt systempaths=unconfined \
reg.ricochet.rs/ricochet/ricochet-server:${VERSION#v}-ubuntu

Docker Compose can also be used:

compose.yml
services:
ricochet-server:
image: reg.ricochet.rs/ricochet/ricochet-server:<version>-ubuntu
container_name: ricochet-server
ports:
- "6188:6188"
cap_drop:
- ALL
cap_add:
- SYS_ADMIN
- SETUID
- SETGID
- DAC_OVERRIDE
security_opt:
- seccomp=unconfined
- systempaths=unconfined
volumes:
- ricochet-data:/var/lib/ricochet/data
- ./ricochet-config.toml:/var/lib/ricochet/data/ricochet-config.toml
restart: unless-stopped
volumes:
ricochet-data:

ricochet runs on port 6188.

Ricochet itself runs Open Container Initiative-compatible rootless containers to run apps and tasks. Doing so from inside of an already unprivileged container needs a wider capability set than what is provided by default.

The required capabilities and security options are documented below. We recommend dropping every default capability and adding only what is needed.

Option Required Purpose
--cap-drop=ALL recommended Drops every default capability.
--cap-add=SYS_ADMIN always Required to mount user and group namespaces.
--cap-add=SETUID always Needed to set user IDs for rootless containers.
--cap-add=SETGID always Needed to set group IDs for rootless containers.
--cap-add=DAC_OVERRIDE always Used to set mount ownership.
--security-opt systempaths=unconfined always Enables mounting /proc in rootless containers.
--security-opt seccomp=unconfined always Allows the syscalls used to create namespaces and mounts.
--security-opt apparmor=<profile> hosts with AppArmor Grants the userns permission that Ubuntu 23.10+ withholds by default. See AppArmor.

Mount a named volume at /var/lib/ricochet/data. Ricochet stores the database, deployment bundles, encryption keys, file logs, the package caches under .cache, and the configuration file in this volume. Prefer a named volume over a bind mount. Docker copies the image’s files into an empty named volume, including the vendored uv and juliaup binaries under data/vendor/ and the default ricochet-config.toml.

If you need a bind mount to a host path, copy the image’s data onto it first:

Terminal window
# copy the image's RICOCHET_HOME to the host before mounting over it
docker create --name ricochet-init reg.ricochet.rs/ricochet/ricochet-server:${VERSION#v}-ubuntu
docker cp ricochet-init:/var/lib/ricochet/data/. /srv/ricochet/
docker rm ricochet-init

Running ricochet in a rootless container prevents item-level memory limits from being enforced. This is because the cgroup is read-only in a rootless container. When an item is spawned with memory limits, those are silently ignored and a warning trace is emitted.

Instead, it is possible to limit the container itself.

Terminal window
docker run --memory=32g --memory-swap=32g ...

To enforce per-item limits, use a host install or Kubernetes.

Ubuntu 23.10 and newer restrict unprivileged user namespaces through AppArmor, which the rootless content containers need. When installed via the .deb or .rpm file the below apparmor profile is created.

/etc/apparmor.d/ricochet
# AppArmor profile for ricochet rootless containers
# This profile grants userns permission required by Ubuntu 23.10+ for
# unprivileged user namespace creation.
abi <abi/4.0>,
include <tunables/global>
profile ricochet /usr/bin/ricochet flags=(unconfined) {
userns,
# Site-specific additions and overrides. See local/README for details.
include if exists <local/ricochet>
}

If deployments fail during environment restore on an AppArmor host, confirm AppArmor is the cause with --security-opt apparmor=unconfined before writing a tailored profile. If that succeeds, create the above AppArmor profile and then enable it:

Terminal window
sudo apparmor_parser -r /etc/apparmor.d/riochet

Deploying content is not supported on OpenShift.