docs(dev): container execution backend + ricochet-server in a container#237
Open
pat-s wants to merge 10 commits into
Open
docs(dev): container execution backend + ricochet-server in a container#237pat-s wants to merge 10 commits into
pat-s wants to merge 10 commits into
Conversation
…container Replaces the "Coming Soon" placeholders for the execution backend reference and the container installation page. - execution-backend.mdx: config schema for engine = "container" with the four required fields, image resolution semantics, daemon access notes, and the two supported deployment scenarios (systemd on host, sibling containers). Includes a callout that remote daemon execution is planned. - installation/2-container.mdx: how to run ricochet-server itself as a container, required volumes, ports, minimal docker run + compose examples, and a section on choosing native vs container vs k8s backend.
Contributor
|
Surge PR preview deployment succeeded. View it at https://ricochet-rs-docs-pr-237.surge.sh |
pat-s
marked this pull request as draft
May 21, 2026 13:29
Renames the default execution backend from "native" to "host" in user-facing docs to reflect that content is run as libcontainer-managed isolated processes rather than plain native child processes. Adds a new "Host vs container on a single host" comparison section to the execution-backend reference, contrasting isolation mechanism, daemon requirement, runtime/exec-env flexibility, observability, and setup cost.
Adds the proxy_host config field (introduced in ricochet/ricochet#481) to the field table, a new "Reachability" subsection explaining why localhost works for systemd-on-host but not for Docker-out-of-Docker, and a three-step DooD checklist with --add-host=host.docker.internal:host-gateway in the example. Also updates the installation page's compose example to match.
- Drop the Reachability and Daemon access subsections (too low-level for this reference) — proxy_host guidance moves into the DooD deployment scenario where it is actionable. - Drop the apt/dnf Docker install tabs; container daemon setup belongs to the OS/distribution, not this reference. - Trim both deployment scenarios to only what is container-backend specific; cross-link to the host and container installation pages for the ricochet-server setup itself. - Add an example ricochet-exec-env.toml showing the category → image mapping and the per-runtime version/binary declarations. - Combine the two silent-failure cautions and the remote-daemon limitation into a single Known issues section at the bottom.
…ity anchor - Add a "Default exec-env images" tip near the top pointing to ricochet-rs/exec-envs as the continuously-updated, production-ready default image set for the container and Kubernetes backends. - Update the ricochet-exec-env.toml example and Image-resolution sample to use real `docker.io/ricochetrs/r-alpine` and `python-ubuntu` images with their actual tags. - Note in the Kubernetes section that the same exec-env config and official images apply unchanged (multi-arch, same runtimes). - Fix link in 2-container.mdx that still pointed to the removed #reachability anchor — repoint to the DooD scenario section.
- Nest Deployment scenarios under Container backend (### / ####) since they only describe container-backend deployment specifics; add a brief lead-in clarifying the install pages own ricochet-server setup itself. - Use docker.io/ricochetrs/ricochet-server everywhere ricochet-server's image is referenced (previously ghcr.io/ricochet-rs/ricochet-server). - Drop literal backticks from Aside titles — they render as plain text, not code, so 'Wrong `proxy_host`' now reads 'Wrong proxy_host'. - Give each Known-issues entry a leading 'Applies to ...' line that cross-links to the relevant section, so each callout is interpretable on its own when read out of context.
…ption, and runtime
pat-s
marked this pull request as ready for review
May 21, 2026 14:51
Member
Author
|
ping @JosiahParry |
JosiahParry
requested changes
Jul 13, 2026
JosiahParry
left a comment
JosiahParry
left a comment
Member
There was a problem hiding this comment.
I didn't finish reviewing line by line but we need to remove all:
- semicolons used that isn't code
- mentions of "category" instead of "image"
- uses of
– - overly specific and mostly irrelevant speicifics
I'd also like to remove mentions of libcontainer. If we feel its necessary, which I don't think it is, we can mention crostini. I think mentioning libcontainer adds extra complexity which isn't needed. To me, the point is that ricochet works out of the box withoutt any system deps and will create rootless OCI-compatible images without any configuration.
|
|
||
| <Aside type="note" title="Coming Soon"> | ||
| This documentation is under construction. | ||
| ricochet runs user content — apps and tasks — in an **execution backend**. |
Member
There was a problem hiding this comment.
Suggested change
| ricochet runs user content — apps and tasks — in an **execution backend**. | |
| ricochet runs content items in an **execution backend**. |
|
|
||
| | Backend | `engine` value | Use when | | ||
| | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------- | | ||
| | Host | (omitted) | Single host, no container daemon. Content runs as isolated processes on the host via [libcontainer][libcontainer]. | |
Member
There was a problem hiding this comment.
Suggested change
| | Host | (omitted) | Single host, no container daemon. Content runs as isolated processes on the host via [libcontainer][libcontainer]. | | |
| | Host | (omitted) | Content runs as a rootless OCI container. | |
| | Backend | `engine` value | Use when | | ||
| | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------- | | ||
| | Host | (omitted) | Single host, no container daemon. Content runs as isolated processes on the host via [libcontainer][libcontainer]. | | ||
| | Container | `container` | Single host with a Docker- or Podman-compatible daemon. Content runs as full containers spawned through the daemon. | |
Member
There was a problem hiding this comment.
Suggested change
| | Container | `container` | Single host with a Docker- or Podman-compatible daemon. Content runs as full containers spawned through the daemon. | | |
| | Container | `container` | Single host with a Docker or Podman-compatible daemon. Content runs as a container spawned through the daemon. | |
| | Container | `container` | Single host with a Docker- or Podman-compatible daemon. Content runs as full containers spawned through the daemon. | | ||
| | Kubernetes | `k8s` | Multi-node cluster, content scheduled as Pods. | | ||
|
|
||
| [libcontainer]: https://docs.rs/libcontainer/ |
Member
There was a problem hiding this comment.
Suggested change
| [libcontainer]: https://docs.rs/libcontainer/ |
| [libcontainer]: https://docs.rs/libcontainer/ | ||
|
|
||
| If `[backend]` is omitted, ricochet uses the **host** backend. | ||
| Content runs as isolated processes managed in-process by `libcontainer` (an OCI-runtime implementation, no daemon required), using the language interpreters installed on the host. |
Member
There was a problem hiding this comment.
Suggested change
| Content runs as isolated processes managed in-process by `libcontainer` (an OCI-runtime implementation, no daemon required), using the language interpreters installed on the host. | |
| Content runs a rootless OCI-compatible container using the language interpreters installed on the host. |
| | Field | Required | Description | | ||
| | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `engine` | yes | Must be `"container"`. | | ||
| | `default_image` | no | Image category name from `exec_env_config_path`. Used when a content item does not specify its own exec environment. | |
Member
There was a problem hiding this comment.
This "category" language needs to be removed 😭
Suggested change
| | `default_image` | no | Image category name from `exec_env_config_path`. Used when a content item does not specify its own exec environment. | | |
| | `default_image` | no | An image name from the `ricochet-exec-env.toml` to be used as a default when no `exec-env` is specified. | |
| | `engine` | yes | Must be `"container"`. | | ||
| | `default_image` | no | Image category name from `exec_env_config_path`. Used when a content item does not specify its own exec environment. | | ||
| | `exec_env_config_path` | yes | Path to the exec-env config TOML. Absolute, or relative to `RICOCHET_HOME`. | | ||
| | `content_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/data/content`. Must contain ricochet's deployment bundles. | |
Member
There was a problem hiding this comment.
Suggested change
| | `content_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/data/content`. Must contain ricochet's deployment bundles. | | |
| | `content_path` | yes | Path that is bind-mounted into every spawned container. Must contain ricochet's deployment bundles. | |
| | `default_image` | no | Image category name from `exec_env_config_path`. Used when a content item does not specify its own exec environment. | | ||
| | `exec_env_config_path` | yes | Path to the exec-env config TOML. Absolute, or relative to `RICOCHET_HOME`. | | ||
| | `content_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/data/content`. Must contain ricochet's deployment bundles. | | ||
| | `cache_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/cache`. Stores R, Julia, and Python package caches shared across content. | |
Member
There was a problem hiding this comment.
Suggested change
| | `cache_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/cache`. Stores R, Julia, and Python package caches shared across content. | | |
| | `cache_path` | yes | Path bind-mounted into every spawned container. Stores R, Julia, and Python package caches shared across content. | |
| | `exec_env_config_path` | yes | Path to the exec-env config TOML. Absolute, or relative to `RICOCHET_HOME`. | | ||
| | `content_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/data/content`. Must contain ricochet's deployment bundles. | | ||
| | `cache_path` | yes | Host path bind-mounted into every spawned container at `/opt/ricochet/cache`. Stores R, Julia, and Python package caches shared across content. | | ||
| | `proxy_host` | no | Hostname ricochet's reverse proxy uses to reach spawned content containers. Defaults to `localhost`; override when running ricochet-server in a container (see [Deployment scenarios](#deployment-scenarios)). | |
Member
There was a problem hiding this comment.
Suggested change
| | `proxy_host` | no | Hostname ricochet's reverse proxy uses to reach spawned content containers. Defaults to `localhost`; override when running ricochet-server in a container (see [Deployment scenarios](#deployment-scenarios)). | | |
| | `proxy_host` | no | Hostname ricochet's reverse proxy uses to reach spawned content containers. Defaults to `localhost`. Override when running ricochet in a container (see [Deployment scenarios](#deployment-scenarios)). | |
| ### Image resolution | ||
|
|
||
| `default_image` and per-content `exec_env` values are looked up in the exec-env config. | ||
| A category like `r-default` resolves to a concrete image reference (`docker.io/ricochetrs/r-alpine:4.5`). |
Member
There was a problem hiding this comment.
Suggested change
| A category like `r-default` resolves to a concrete image reference (`docker.io/ricochetrs/r-alpine:4.5`). | |
| For example, `r-default` resolves to a concrete image reference (`docker.io/ricochetrs/r-alpine:4.5`). |
JosiahParry
reviewed
Jul 13, 2026
Comment on lines
+35
to
+46
| ## Minimal run | ||
|
|
||
| ```sh | ||
| docker run -d \ | ||
| --name ricochet-server \ | ||
| -p 6188:6188 \ | ||
| -v /var/lib/ricochet:/var/lib/ricochet \ | ||
| docker.io/ricochetrs/ricochet-server:latest | ||
| ``` | ||
|
|
||
| Place your `ricochet-config.toml` at `/var/lib/ricochet/ricochet-config.toml` on the host. | ||
| ricochet-server reads it on startup from the bind-mounted location. |
Member
There was a problem hiding this comment.
FWIW, I still can't get ricochet-server to run code in a container. I don't think this should be published yet.
Comment on lines
+59
to
+61
| ### Container backend (sibling containers) | ||
|
|
||
| To spawn each piece of user content as its own container on the host, configure the [container backend](/dev/admin/configuration/execution-backend/#container-backend), mount the host's container daemon socket into ricochet-server, and make sure ricochet-server can reach the host network so it can proxy to spawned containers: |
Member
There was a problem hiding this comment.
Is this covered by the DooD section?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the container execution backend (ricochet/ricochet#481) and the ricochet-server-in-a-container install path. Both pages were previously "Coming Soon" placeholders.
Pages
dev/admin/configuration/execution-backend.mdxengine = "container", four required fields)DOCKER_HOST, permissions)dev/admin/installation/2-container.mdxdocker run+compose.ymlexamples