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.

Image

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. Note that there is no latest tag.

Quickstart

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

[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:

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:

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:

Note that ricochet runs on port 6188.

Security options

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. Note that 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.

Required volumes

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. Use a named volume, because 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:

# 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

Limitations

Memory limits

To enforce each item’s memory limit, start the container as root:

docker run --user 0 ...

In Docker Compose, set user: "0" on the service.

The image then makes the container’s cgroup writable for ricochet and starts the server as its usual non-root user. This needs --cap-add=SYS_ADMIN, which the commands above already grant.

Without --user 0, items run without a memory limit and the server logs per-item memory limits are not enforced at startup. To cap memory anyway, limit the whole container:

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

AppArmor

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.

# 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:

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

OpenShift

Deploying content is not supported on OpenShift.