From 9d99cba6ce6999fa7e421cd8946a5b5add85af9f Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 15:24:30 +0200
Subject: [PATCH 1/8] docs(dev): document container execution backend +
 ricochet-server in 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.
---
 .../admin/configuration/execution-backend.mdx | 143 +++++++++++++++++-
 .../dev/admin/installation/2-container.mdx    |  94 +++++++++++-
 2 files changed, 231 insertions(+), 6 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index baf5f40..c492e1b 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -2,8 +2,145 @@
 title: Execution Backend
 ---
 
-import { Aside } from "@astrojs/starlight/components";
+import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
 
-<Aside type="note" title="Coming Soon">
-  This documentation is under construction.
+ricochet runs user content — apps and tasks — in an **execution backend**.
+Two backends are supported:
+
+| Backend      | `engine` value | Use when                                                                 |
+| ------------ | -------------- | ------------------------------------------------------------------------ |
+| Native       | (omitted)      | Single host, no isolation needed, interpreters installed directly.       |
+| Container    | `container`    | Single host with Docker or Podman, content runs in isolated containers.  |
+| Kubernetes   | `k8s`          | Multi-node cluster, content scheduled as Pods.                           |
+
+If `[backend]` is omitted entirely, ricochet runs content as native child processes using the interpreters installed on the host.
+This page documents the `container` and `k8s` backends.
+
+## Container backend
+
+Set `engine = "container"` to spawn content as containers via a local Docker- or Podman-compatible daemon.
+ricochet talks to the daemon over its Unix socket (`/var/run/docker.sock` by default, or whatever `DOCKER_HOST` points to).
+
+```toml title="ricochet-config.toml"
+[backend]
+engine = "container"
+default_image = "r-default"
+exec_env_config_path = "ricochet-exec-env.toml"
+content_path = "/var/lib/ricochet/data/content"
+cache_path = "/var/lib/ricochet/data/.cache"
+```
+
+| 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.                                         |
+| `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.              |
+
+ricochet refuses to start if `exec_env_config_path`, `content_path`, or `cache_path` is missing — silently launching containers with broken mounts would corrupt deployments.
+
+### 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 (`registry.example.com/ricochet/exec-env-r:4.5`).
+If the value does not match a category, ricochet treats it as a full image reference and uses it as-is.
+
+### Daemon access
+
+ricochet uses [`bollard`](https://docs.rs/bollard) to talk to the daemon.
+Connection target follows standard `DOCKER_HOST` semantics:
+
+- Unset: connects to `/var/run/docker.sock`.
+- `unix:///path/to/socket`: connects to that Unix socket.
+- `tcp://host:port`: connects over TCP (TLS is not yet configurable — local daemons only).
+
+The user running `ricochet-server` must have read/write access to the socket.
+On Linux this typically means adding the user to the `docker` group (or running as root, as the systemd service does by default).
+
+## Deployment scenarios
+
+### ricochet-server via systemd (on the host)
+
+The container daemon and ricochet-server both run on the same host.
+ricochet writes deployment bundles to `content_path` on its filesystem, then asks the daemon to bind-mount that same path into spawned containers.
+Because both processes see the same filesystem, the host path in `content_path` resolves consistently.
+
+<Tabs>
+  <TabItem label="Debian / Ubuntu">
+    ```sh
+    sudo apt install docker.io
+    sudo usermod -aG docker ricochet     # only if ricochet-server runs as a non-root user
+    sudo systemctl enable --now docker
+    sudo systemctl restart ricochet-server
+    ```
+  </TabItem>
+  <TabItem label="RHEL / AlmaLinux">
+    ```sh
+    sudo dnf install podman-docker
+    sudo systemctl enable --now podman.socket
+    sudo systemctl restart ricochet-server
+    ```
+    Podman exposes a Docker-compatible socket at `/run/podman/podman.sock`.
+    Set `DOCKER_HOST=unix:///run/podman/podman.sock` in `ricochet-server.service` if it is not the default socket on your distribution.
+  </TabItem>
+</Tabs>
+
+### ricochet-server in a container (sibling containers)
+
+ricochet-server itself runs as a container and uses the host's daemon to spawn sibling containers for user content.
+This is sometimes called "Docker-out-of-Docker" (DooD).
+
+Two things must line up.
+
+**1. The daemon socket must be reachable from inside the ricochet container.**
+Bind-mount `/var/run/docker.sock` into the ricochet container.
+
+**2. Bind-mount paths must resolve to the same physical location on host and inside ricochet.**
+The daemon resolves `content_path` and `cache_path` against the **host** filesystem, not the ricochet container's view.
+The simplest correct setup is to mount the host data directory into the ricochet container at the same path used in `content_path` / `cache_path`.
+
+```sh
+docker run -d \
+  --name ricochet-server \
+  -p 6188:6188 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /var/lib/ricochet:/var/lib/ricochet \
+  ghcr.io/ricochet-rs/ricochet-server:latest
+```
+
+With matching paths inside and outside, the same `content_path = "/var/lib/ricochet/data/content"` works from either perspective.
+
+<Aside type="caution" title="Path mismatch is silent">
+  If `content_path` points to a path that does not exist on the host, the daemon will still launch the sibling container — but bind-mount the wrong (or empty) directory.
+  Content items will appear to deploy but fail at runtime because their bundles are not visible.
+  Always verify that `ls $content_path` works on the **host**, not just inside the ricochet container.
+</Aside>
+
+See [Container installation](/dev/admin/installation/2-container/) for the full ricochet-server-in-a-container setup.
+
+## Kubernetes backend
+
+For multi-node clusters, use `engine = "k8s"`.
+ricochet creates a Deployment per app and a Job per task using the cluster's API.
+
+```toml title="ricochet-config.toml"
+[backend]
+engine = "k8s"
+namespace = "ricochet"
+default_image = "r-default"
+exec_env_config_path = "/etc/ricochet/exec-env.toml"
+pvc_content_name = "ricochet-content"
+pvc_cache_name = "ricochet-cache"
+image_pull_policy = "IfNotPresent"
+```
+
+See [Kubernetes installation](/dev/admin/installation/3-kubernetes/) for cluster prerequisites, Helm chart values, and PVC sizing guidance.
+
+## Remote daemon execution
+
+<Aside type="note" title="Planned">
+  Spawning content on a **remote** container daemon — a separate host from where ricochet-server runs — is on the roadmap.
+  This requires (a) TLS material configuration for `bollard::Docker::connect_with_ssl`, and (b) a deliberate strategy for `content_path` / `cache_path` since bind mounts resolve on the daemon's host (likely via shared NFS, named volumes, or per-content image baking).
+  Until then, use the Kubernetes backend for multi-host execution.
 </Aside>
diff --git a/src/content/docs/dev/admin/installation/2-container.mdx b/src/content/docs/dev/admin/installation/2-container.mdx
index cb41b1b..b4f3f5f 100644
--- a/src/content/docs/dev/admin/installation/2-container.mdx
+++ b/src/content/docs/dev/admin/installation/2-container.mdx
@@ -2,8 +2,96 @@
 title: Container
 ---
 
-import { Aside } from "@astrojs/starlight/components";
+import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
 
-<Aside type="note" title="Coming Soon">
-  This documentation is under construction.
+Run ricochet-server itself as a container.
+This is the same `ricochet-server` binary as the [host install](/dev/admin/installation/1-host/), packaged as an image.
+
+## Image
+
+```
+ghcr.io/ricochet-rs/ricochet-server:<version>
+```
+
+Tags follow the ricochet release version (e.g. `v0.7.3`).
+A `latest` tag tracks the most recent stable release.
+
+## Required volumes
+
+Two host directories must be persisted across container restarts:
+
+| Mount target            | Purpose                                                                     |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `/var/lib/ricochet`     | Database, deployment bundles, encryption keys, file logs.                   |
+| `/var/lib/ricochet/data/.cache` | R, Julia, and Python package caches. Share across content runs.     |
+
+The cache directory lives under `RICOCHET_HOME` by default, so mounting `/var/lib/ricochet` covers both.
+Separate them only if you want the cache on a different volume (e.g. faster local disk vs. networked storage).
+
+## Ports
+
+ricochet-server listens on **6188** by default.
+
+## Minimal run
+
+```sh
+docker run -d \
+  --name ricochet-server \
+  -p 6188:6188 \
+  -v /var/lib/ricochet:/var/lib/ricochet \
+  ghcr.io/ricochet-rs/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.
+
+## Spawning user content
+
+The execution backend ricochet uses for spawning user content (apps, tasks) is independent of how ricochet-server itself runs.
+
+### Native (default)
+
+With no `[backend]` block in `ricochet-config.toml`, ricochet-server runs content as child processes **inside** its own container.
+Suitable for small single-tenant setups; content shares the ricochet image's interpreters.
+
+### 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) and mount the host's container daemon socket into ricochet-server:
+
+```sh
+docker run -d \
+  --name ricochet-server \
+  -p 6188:6188 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /var/lib/ricochet:/var/lib/ricochet \
+  ghcr.io/ricochet-rs/ricochet-server:latest
+```
+
+Set `content_path` and `cache_path` in `ricochet-config.toml` to paths that exist on the **host**.
+With the example mount above, `content_path = "/var/lib/ricochet/data/content"` resolves to the same physical directory from both ricochet-server's view and the host daemon's view — sibling containers see the deployment bundles ricochet-server wrote.
+
+<Aside type="caution" title="Paths are host paths">
+  The daemon resolves `content_path` and `cache_path` against the host filesystem, not the ricochet-server container's view.
+  Mount the host data directory into the ricochet-server container at the **same path** used in the config, or sibling containers will mount empty directories and content will fail to start.
 </Aside>
+
+See the [execution backend reference](/dev/admin/configuration/execution-backend/) for the full field reference and image-resolution semantics.
+
+### Kubernetes backend
+
+For multi-node setups, do not run ricochet-server as a standalone container — use the [Kubernetes installation](/dev/admin/installation/3-kubernetes/) instead.
+
+## Compose example
+
+```yaml title="compose.yml"
+services:
+  ricochet-server:
+    image: ghcr.io/ricochet-rs/ricochet-server:latest
+    container_name: ricochet-server
+    ports:
+      - "6188:6188"
+    volumes:
+      - /var/lib/ricochet:/var/lib/ricochet
+      - /var/run/docker.sock:/var/run/docker.sock   # only for container backend
+    restart: unless-stopped
+```

From 863a716757fc09c2726fd48b73839d4981da23fc Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 15:36:14 +0200
Subject: [PATCH 2/8] docs(dev): rename native backend to host; clarify
 libcontainer isolation

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.
---
 .../admin/configuration/execution-backend.mdx | 37 +++++++++++++++----
 .../dev/admin/installation/2-container.mdx    |  8 ++--
 2 files changed, 34 insertions(+), 11 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index c492e1b..3c71518 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -5,16 +5,37 @@ title: Execution Backend
 import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
 
 ricochet runs user content — apps and tasks — in an **execution backend**.
-Two backends are supported:
+Three backends are supported:
 
-| Backend      | `engine` value | Use when                                                                 |
-| ------------ | -------------- | ------------------------------------------------------------------------ |
-| Native       | (omitted)      | Single host, no isolation needed, interpreters installed directly.       |
-| Container    | `container`    | Single host with Docker or Podman, content runs in isolated containers.  |
-| Kubernetes   | `k8s`          | Multi-node cluster, content scheduled as Pods.                           |
+| 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. |
+| Kubernetes   | `k8s`          | Multi-node cluster, content scheduled as Pods.                                                                    |
 
-If `[backend]` is omitted entirely, ricochet runs content as native child processes using the interpreters installed on the host.
-This page documents the `container` and `k8s` backends.
+[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.
+This page documents the `container` and `k8s` backends; the host backend has no configuration knobs of its own.
+
+## Host vs container on a single host
+
+Both backends run content on the same machine as ricochet-server.
+The difference is **how** content is isolated and **where** the runtime environment comes from.
+
+| Dimension                | Host backend (`libcontainer`)                                          | Container backend (`container`)                                  |
+| ------------------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Isolation mechanism      | `libcontainer` namespaces/cgroups, set up in-process by ricochet-server | OCI containers, spawned by the host's Docker/Podman daemon       |
+| Daemon required          | No                                                                     | Yes (Docker, Podman, or compatible)                              |
+| Runtime / interpreters   | Whatever is installed on the host (system R, Python, Julia)            | Whatever the chosen image provides; arbitrary per content item   |
+| Per-content exec env     | Single shared host environment                                         | Per-item via `exec_env` → image, like the Kubernetes backend     |
+| Observability            | Processes are not visible to `docker ps` / container metrics tooling   | Each app/task is a real container — visible to standard tooling  |
+| Setup cost               | None — works on a fresh ricochet-server install                        | Install and run a container daemon, grant socket access          |
+
+Pick the **host** backend for simple single-tenant deployments where the host already has the interpreters you need and you do not want to operate a container daemon.
+
+Pick the **container** backend when you need different runtime environments per content item (e.g. R 4.3 vs R 4.5, conflicting system libraries), or when you want each running app and task to be a visible, individually observable container.
 
 ## Container backend
 
diff --git a/src/content/docs/dev/admin/installation/2-container.mdx b/src/content/docs/dev/admin/installation/2-container.mdx
index b4f3f5f..04c1f50 100644
--- a/src/content/docs/dev/admin/installation/2-container.mdx
+++ b/src/content/docs/dev/admin/installation/2-container.mdx
@@ -49,10 +49,12 @@ ricochet-server reads it on startup from the bind-mounted location.
 
 The execution backend ricochet uses for spawning user content (apps, tasks) is independent of how ricochet-server itself runs.
 
-### Native (default)
+### Host (default)
 
-With no `[backend]` block in `ricochet-config.toml`, ricochet-server runs content as child processes **inside** its own container.
-Suitable for small single-tenant setups; content shares the ricochet image's interpreters.
+With no `[backend]` block in `ricochet-config.toml`, ricochet-server runs content as [libcontainer](https://docs.rs/libcontainer/)-managed isolated processes **inside** its own container, using the interpreters baked into the ricochet-server image.
+Suitable for small single-tenant setups where every content item can share the same runtime environment.
+
+See [Host vs container on a single host](/dev/admin/configuration/execution-backend/#host-vs-container-on-a-single-host) for the tradeoff.
 
 ### Container backend (sibling containers)
 

From 03c554a0384f73fad1c47f448b08bba33cb3e0c7 Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 15:42:33 +0200
Subject: [PATCH 3/8] docs(dev): document proxy_host for the container backend

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.
---
 .../admin/configuration/execution-backend.mdx | 37 ++++++++++++++++++-
 .../dev/admin/installation/2-container.mdx    | 16 +++++---
 2 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index 3c71518..95ace67 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -58,9 +58,19 @@ cache_path = "/var/lib/ricochet/data/.cache"
 | `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`. See [Reachability](#reachability) below.                |
 
 ricochet refuses to start if `exec_env_config_path`, `content_path`, or `cache_path` is missing — silently launching containers with broken mounts would corrupt deployments.
 
+### Reachability
+
+Each spawned content container publishes its app port to the host's `0.0.0.0`.
+ricochet's pingora reverse proxy then connects to that port to route incoming traffic.
+The hostname pingora uses is `proxy_host` — `localhost` by default.
+
+That default works in the **systemd-on-host** scenario because ricochet-server and the published port share the host's network namespace.
+It does **not** work for **Docker-out-of-Docker**: `localhost` inside the ricochet-server container is that container's loopback, not the host, so the published port is unreachable. See [Deployment scenarios](#deployment-scenarios) below for the fix.
+
 ### Image resolution
 
 `default_image` and per-content `exec_env` values are looked up in the exec-env config.
@@ -112,7 +122,7 @@ Because both processes see the same filesystem, the host path in `content_path`
 ricochet-server itself runs as a container and uses the host's daemon to spawn sibling containers for user content.
 This is sometimes called "Docker-out-of-Docker" (DooD).
 
-Two things must line up.
+Three things must line up.
 
 **1. The daemon socket must be reachable from inside the ricochet container.**
 Bind-mount `/var/run/docker.sock` into the ricochet container.
@@ -121,15 +131,33 @@ Bind-mount `/var/run/docker.sock` into the ricochet container.
 The daemon resolves `content_path` and `cache_path` against the **host** filesystem, not the ricochet container's view.
 The simplest correct setup is to mount the host data directory into the ricochet container at the same path used in `content_path` / `cache_path`.
 
-```sh
+**3. `proxy_host` must point to an address ricochet-server can reach.**
+Sibling content containers publish their app port to the host's `0.0.0.0`, not to the ricochet-server container's loopback.
+Pick one of these (in rough order of preference):
+
+- `--network host` for the ricochet-server container — `localhost` becomes the host's localhost, the default `proxy_host` works without further config. Trades container network isolation for the simplest setup.
+- `proxy_host = "host.docker.internal"` — works on Docker Desktop (macOS, Windows) and on Linux Docker when you pass `--add-host=host.docker.internal:host-gateway` to the ricochet-server container.
+- `proxy_host = "<host-ip>"` — the host's bridge or LAN IP. Stable but environment-specific.
+
+```sh title="Bridge network with host-gateway alias"
 docker run -d \
   --name ricochet-server \
   -p 6188:6188 \
+  --add-host=host.docker.internal:host-gateway \
   -v /var/run/docker.sock:/var/run/docker.sock \
   -v /var/lib/ricochet:/var/lib/ricochet \
   ghcr.io/ricochet-rs/ricochet-server:latest
 ```
 
+```toml title="ricochet-config.toml (DooD)"
+[backend]
+engine = "container"
+exec_env_config_path = "ricochet-exec-env.toml"
+content_path = "/var/lib/ricochet/data/content"
+cache_path = "/var/lib/ricochet/data/.cache"
+proxy_host = "host.docker.internal"
+```
+
 With matching paths inside and outside, the same `content_path = "/var/lib/ricochet/data/content"` works from either perspective.
 
 <Aside type="caution" title="Path mismatch is silent">
@@ -138,6 +166,11 @@ With matching paths inside and outside, the same `content_path = "/var/lib/ricoc
   Always verify that `ls $content_path` works on the **host**, not just inside the ricochet container.
 </Aside>
 
+<Aside type="caution" title="Wrong `proxy_host` is silent too">
+  If `proxy_host` resolves but does not actually reach the host (typo, wrong IP, missing `--add-host`), spawned content containers will start and pass health checks at the container layer, but pingora will get a connection refused or timeout when it tries to proxy a request.
+  You will see this as 502s in the ricochet UI for the affected content.
+</Aside>
+
 See [Container installation](/dev/admin/installation/2-container/) for the full ricochet-server-in-a-container setup.
 
 ## Kubernetes backend
diff --git a/src/content/docs/dev/admin/installation/2-container.mdx b/src/content/docs/dev/admin/installation/2-container.mdx
index 04c1f50..3a4dfc4 100644
--- a/src/content/docs/dev/admin/installation/2-container.mdx
+++ b/src/content/docs/dev/admin/installation/2-container.mdx
@@ -58,26 +58,30 @@ See [Host vs container on a single host](/dev/admin/configuration/execution-back
 
 ### 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) and mount the host's container daemon socket into ricochet-server:
+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:
 
 ```sh
 docker run -d \
   --name ricochet-server \
   -p 6188:6188 \
+  --add-host=host.docker.internal:host-gateway \
   -v /var/run/docker.sock:/var/run/docker.sock \
   -v /var/lib/ricochet:/var/lib/ricochet \
   ghcr.io/ricochet-rs/ricochet-server:latest
 ```
 
-Set `content_path` and `cache_path` in `ricochet-config.toml` to paths that exist on the **host**.
-With the example mount above, `content_path = "/var/lib/ricochet/data/content"` resolves to the same physical directory from both ricochet-server's view and the host daemon's view — sibling containers see the deployment bundles ricochet-server wrote.
+Set in `ricochet-config.toml`:
+
+- `content_path` and `cache_path` to paths that exist on the **host**.
+  With the example mount above, `content_path = "/var/lib/ricochet/data/content"` resolves to the same physical directory from both ricochet-server's view and the host daemon's view — sibling containers see the deployment bundles ricochet-server wrote.
+- `proxy_host = "host.docker.internal"` so pingora reaches the host's published ports instead of ricochet-server's own loopback.
 
 <Aside type="caution" title="Paths are host paths">
   The daemon resolves `content_path` and `cache_path` against the host filesystem, not the ricochet-server container's view.
   Mount the host data directory into the ricochet-server container at the **same path** used in the config, or sibling containers will mount empty directories and content will fail to start.
 </Aside>
 
-See the [execution backend reference](/dev/admin/configuration/execution-backend/) for the full field reference and image-resolution semantics.
+See the [execution backend reference](/dev/admin/configuration/execution-backend/#reachability) for `proxy_host` alternatives (`--network host`, explicit host IP) and the full field reference.
 
 ### Kubernetes backend
 
@@ -92,8 +96,10 @@ services:
     container_name: ricochet-server
     ports:
       - "6188:6188"
+    extra_hosts:
+      - "host.docker.internal:host-gateway" # only for container backend
     volumes:
       - /var/lib/ricochet:/var/lib/ricochet
-      - /var/run/docker.sock:/var/run/docker.sock   # only for container backend
+      - /var/run/docker.sock:/var/run/docker.sock # only for container backend
     restart: unless-stopped
 ```

From abd73557dacb16fb79e0013798e0a505a92592ec Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 16:22:04 +0200
Subject: [PATCH 4/8] docs(dev): trim execution-backend reference, add exec-env
 example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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.
---
 .../admin/configuration/execution-backend.mdx | 143 ++++++++----------
 1 file changed, 62 insertions(+), 81 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index 95ace67..cf81b59 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -2,7 +2,7 @@
 title: Execution Backend
 ---
 
-import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
+import { Aside } from "@astrojs/starlight/components";
 
 ricochet runs user content — apps and tasks — in an **execution backend**.
 Three backends are supported:
@@ -40,7 +40,6 @@ Pick the **container** backend when you need different runtime environments per
 ## Container backend
 
 Set `engine = "container"` to spawn content as containers via a local Docker- or Podman-compatible daemon.
-ricochet talks to the daemon over its Unix socket (`/var/run/docker.sock` by default, or whatever `DOCKER_HOST` points to).
 
 ```toml title="ricochet-config.toml"
 [backend]
@@ -58,18 +57,9 @@ cache_path = "/var/lib/ricochet/data/.cache"
 | `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`. See [Reachability](#reachability) below.                |
+| `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)). |
 
-ricochet refuses to start if `exec_env_config_path`, `content_path`, or `cache_path` is missing — silently launching containers with broken mounts would corrupt deployments.
-
-### Reachability
-
-Each spawned content container publishes its app port to the host's `0.0.0.0`.
-ricochet's pingora reverse proxy then connects to that port to route incoming traffic.
-The hostname pingora uses is `proxy_host` — `localhost` by default.
-
-That default works in the **systemd-on-host** scenario because ricochet-server and the published port share the host's network namespace.
-It does **not** work for **Docker-out-of-Docker**: `localhost` inside the ricochet-server container is that container's loopback, not the host, so the published port is unreachable. See [Deployment scenarios](#deployment-scenarios) below for the fix.
+ricochet refuses to start if `exec_env_config_path`, `content_path`, or `cache_path` is missing.
 
 ### Image resolution
 
@@ -77,67 +67,63 @@ It does **not** work for **Docker-out-of-Docker**: `localhost` inside the ricoch
 A category like `r-default` resolves to a concrete image reference (`registry.example.com/ricochet/exec-env-r:4.5`).
 If the value does not match a category, ricochet treats it as a full image reference and uses it as-is.
 
-### Daemon access
-
-ricochet uses [`bollard`](https://docs.rs/bollard) to talk to the daemon.
-Connection target follows standard `DOCKER_HOST` semantics:
-
-- Unset: connects to `/var/run/docker.sock`.
-- `unix:///path/to/socket`: connects to that Unix socket.
-- `tcp://host:port`: connects over TCP (TLS is not yet configurable — local daemons only).
+### Exec-env config
+
+The exec-env config TOML maps category names to concrete container images and declares the language runtimes inside each image.
+Content items pick a category via their `exec_env` setting; ricochet falls back to `default_image` when none is set.
+
+```toml title="ricochet-exec-env.toml"
+[image.r-default]
+image = "reg.ricochet.rs/ricochet/exec-env-r:4.5-alpine"
+os = "alpine-3.22"
+arch = ["linux/amd64", "linux/arm64"]
+description = "Default R 4.5 environment"
+r = [
+  { version = "4.5.1", bin = "/opt/R/4.5.1/bin/R" },
+]
+
+[image.r-4-4]
+image = "reg.ricochet.rs/ricochet/exec-env-r:4.4-alpine"
+os = "alpine-3.21"
+arch = ["linux/amd64", "linux/arm64"]
+r = [
+  { version = "4.4.1", bin = "/opt/R/4.4.1/bin/R" },
+  { version = "4.4.2", bin = "/opt/R/4.4.2/bin/R" },
+]
+
+[image.python-default]
+image = "reg.ricochet.rs/ricochet/exec-env-python:3.12"
+os = "ubuntu-22.04"
+arch = ["linux/amd64", "linux/arm64"]
+python = [
+  { version = "3.12.0", bin = "/usr/local/bin/python3" },
+]
+```
 
-The user running `ricochet-server` must have read/write access to the socket.
-On Linux this typically means adding the user to the `docker` group (or running as root, as the systemd service does by default).
+`r`, `python`, and `julia` arrays declare the interpreter versions present in the image and the path to their binaries — ricochet uses these to match a content item's required version against an available runtime.
 
 ## Deployment scenarios
 
 ### ricochet-server via systemd (on the host)
 
-The container daemon and ricochet-server both run on the same host.
-ricochet writes deployment bundles to `content_path` on its filesystem, then asks the daemon to bind-mount that same path into spawned containers.
-Because both processes see the same filesystem, the host path in `content_path` resolves consistently.
-
-<Tabs>
-  <TabItem label="Debian / Ubuntu">
-    ```sh
-    sudo apt install docker.io
-    sudo usermod -aG docker ricochet     # only if ricochet-server runs as a non-root user
-    sudo systemctl enable --now docker
-    sudo systemctl restart ricochet-server
-    ```
-  </TabItem>
-  <TabItem label="RHEL / AlmaLinux">
-    ```sh
-    sudo dnf install podman-docker
-    sudo systemctl enable --now podman.socket
-    sudo systemctl restart ricochet-server
-    ```
-    Podman exposes a Docker-compatible socket at `/run/podman/podman.sock`.
-    Set `DOCKER_HOST=unix:///run/podman/podman.sock` in `ricochet-server.service` if it is not the default socket on your distribution.
-  </TabItem>
-</Tabs>
+Set up ricochet-server first — see [Host installation](/dev/admin/installation/1-host/).
 
-### ricochet-server in a container (sibling containers)
+Container-backend specifics:
 
-ricochet-server itself runs as a container and uses the host's daemon to spawn sibling containers for user content.
-This is sometimes called "Docker-out-of-Docker" (DooD).
+- The daemon and ricochet-server share the host's filesystem, so `content_path` and `cache_path` resolve consistently on both sides — nothing to translate.
+- The user running ricochet-server needs read/write access to the daemon socket (typically by adding it to the `docker` group, or running as root as the default systemd unit does).
+- `proxy_host` can stay at its default `localhost` since both processes share the host's network namespace.
 
-Three things must line up.
-
-**1. The daemon socket must be reachable from inside the ricochet container.**
-Bind-mount `/var/run/docker.sock` into the ricochet container.
+### ricochet-server in a container (sibling containers)
 
-**2. Bind-mount paths must resolve to the same physical location on host and inside ricochet.**
-The daemon resolves `content_path` and `cache_path` against the **host** filesystem, not the ricochet container's view.
-The simplest correct setup is to mount the host data directory into the ricochet container at the same path used in `content_path` / `cache_path`.
+Set up ricochet-server in a container first — see [Container installation](/dev/admin/installation/2-container/).
 
-**3. `proxy_host` must point to an address ricochet-server can reach.**
-Sibling content containers publish their app port to the host's `0.0.0.0`, not to the ricochet-server container's loopback.
-Pick one of these (in rough order of preference):
+ricochet-server runs as a container and uses the host's daemon to spawn sibling containers for user content — sometimes called "Docker-out-of-Docker" (DooD).
+Three container-backend specifics apply:
 
-- `--network host` for the ricochet-server container — `localhost` becomes the host's localhost, the default `proxy_host` works without further config. Trades container network isolation for the simplest setup.
-- `proxy_host = "host.docker.internal"` — works on Docker Desktop (macOS, Windows) and on Linux Docker when you pass `--add-host=host.docker.internal:host-gateway` to the ricochet-server container.
-- `proxy_host = "<host-ip>"` — the host's bridge or LAN IP. Stable but environment-specific.
+1. **Bind-mount the daemon socket** (`/var/run/docker.sock`) into the ricochet-server container.
+2. **Match host and ricochet-server paths for `content_path` and `cache_path`.** The daemon resolves these against the **host** filesystem, not ricochet-server's view, so the simplest correct setup mounts the host data directory at the same path inside the ricochet-server container.
+3. **Set `proxy_host` to an address ricochet-server can reach.** Sibling content containers publish their app ports to the host, not to ricochet-server's loopback. Either run ricochet-server with `--network host` (default `proxy_host` works), or use `--add-host=host.docker.internal:host-gateway` together with `proxy_host = "host.docker.internal"`, or set `proxy_host` to the host's IP.
 
 ```sh title="Bridge network with host-gateway alias"
 docker run -d \
@@ -158,21 +144,6 @@ cache_path = "/var/lib/ricochet/data/.cache"
 proxy_host = "host.docker.internal"
 ```
 
-With matching paths inside and outside, the same `content_path = "/var/lib/ricochet/data/content"` works from either perspective.
-
-<Aside type="caution" title="Path mismatch is silent">
-  If `content_path` points to a path that does not exist on the host, the daemon will still launch the sibling container — but bind-mount the wrong (or empty) directory.
-  Content items will appear to deploy but fail at runtime because their bundles are not visible.
-  Always verify that `ls $content_path` works on the **host**, not just inside the ricochet container.
-</Aside>
-
-<Aside type="caution" title="Wrong `proxy_host` is silent too">
-  If `proxy_host` resolves but does not actually reach the host (typo, wrong IP, missing `--add-host`), spawned content containers will start and pass health checks at the container layer, but pingora will get a connection refused or timeout when it tries to proxy a request.
-  You will see this as 502s in the ricochet UI for the affected content.
-</Aside>
-
-See [Container installation](/dev/admin/installation/2-container/) for the full ricochet-server-in-a-container setup.
-
 ## Kubernetes backend
 
 For multi-node clusters, use `engine = "k8s"`.
@@ -191,10 +162,20 @@ image_pull_policy = "IfNotPresent"
 
 See [Kubernetes installation](/dev/admin/installation/3-kubernetes/) for cluster prerequisites, Helm chart values, and PVC sizing guidance.
 
-## Remote daemon execution
+## Known issues
+
+<Aside type="caution" title="Path mismatch is silent">
+  If `content_path` points to a path that does not exist on the host, the daemon still launches the spawned container — but bind-mounts the wrong (or empty) directory.
+  Content items will appear to deploy but fail at runtime because their bundles are not visible.
+  Verify `ls $content_path` works on the **host**, not just inside the ricochet-server container.
+</Aside>
+
+<Aside type="caution" title="Wrong `proxy_host` is silent too">
+  If `proxy_host` resolves but does not actually reach the host (typo, wrong IP, missing `--add-host`), spawned content containers start and pass health checks at the container layer, but ricochet's reverse proxy gets a connection refused or timeout when it tries to route a request — surfacing as 502s in the UI.
+</Aside>
 
-<Aside type="note" title="Planned">
-  Spawning content on a **remote** container daemon — a separate host from where ricochet-server runs — is on the roadmap.
-  This requires (a) TLS material configuration for `bollard::Docker::connect_with_ssl`, and (b) a deliberate strategy for `content_path` / `cache_path` since bind mounts resolve on the daemon's host (likely via shared NFS, named volumes, or per-content image baking).
+<Aside type="note" title="Remote daemons not yet supported">
+  ricochet currently only talks to a daemon on the same host as ricochet-server.
+  Remote daemon support is on the roadmap and requires TLS configuration plus a deliberate strategy for `content_path` / `cache_path` (bind mounts resolve on the daemon's host — shared NFS, named volumes, or per-content image baking).
   Until then, use the Kubernetes backend for multi-host execution.
 </Aside>

From b5fdd3c59ff52262d704f6cd52da1d6bed2283d5 Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 16:27:19 +0200
Subject: [PATCH 5/8] docs(dev): mention official exec-env images and fix
 dropped reachability anchor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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.
---
 .../admin/configuration/execution-backend.mdx | 34 ++++++++++++-------
 .../dev/admin/installation/2-container.mdx    |  2 +-
 2 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index cf81b59..cae8818 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -19,6 +19,12 @@ 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.
 This page documents the `container` and `k8s` backends; the host backend has no configuration knobs of its own.
 
+<Aside type="tip" title="Default exec-env images">
+  The container and Kubernetes backends pull an OCI image per content item.
+  ricochet publishes a continuously-updated set of production-ready images at [ricochet-rs/exec-envs](https://github.com/ricochet-rs/exec-envs) — R on Alpine, Ubuntu, and AlmaLinux; Python on Ubuntu and AlmaLinux — rebuilt weekly and suitable as defaults for `default_image` and per-content `exec_env` references.
+  Bring your own images when you need additional system libraries or a different language/version combination.
+</Aside>
+
 ## Host vs container on a single host
 
 Both backends run content on the same machine as ricochet-server.
@@ -64,7 +70,7 @@ ricochet refuses to start if `exec_env_config_path`, `content_path`, or `cache_p
 ### 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 (`registry.example.com/ricochet/exec-env-r:4.5`).
+A category like `r-default` resolves to a concrete image reference (`docker.io/ricochetrs/r-alpine:4.5`).
 If the value does not match a category, ricochet treats it as a full image reference and uses it as-is.
 
 ### Exec-env config
@@ -72,31 +78,33 @@ If the value does not match a category, ricochet treats it as a full image refer
 The exec-env config TOML maps category names to concrete container images and declares the language runtimes inside each image.
 Content items pick a category via their `exec_env` setting; ricochet falls back to `default_image` when none is set.
 
+The example below references the [official ricochet exec-env images](https://github.com/ricochet-rs/exec-envs) — adjust the image and tag, or substitute your own.
+
 ```toml title="ricochet-exec-env.toml"
 [image.r-default]
-image = "reg.ricochet.rs/ricochet/exec-env-r:4.5-alpine"
-os = "alpine-3.22"
+image = "docker.io/ricochetrs/r-alpine:4.5"
+os = "alpine-3.23"
 arch = ["linux/amd64", "linux/arm64"]
-description = "Default R 4.5 environment"
+description = "Default R 4.5 environment (Alpine)"
 r = [
-  { version = "4.5.1", bin = "/opt/R/4.5.1/bin/R" },
+  { version = "4.5.3", bin = "/usr/bin/R" },
 ]
 
-[image.r-4-4]
-image = "reg.ricochet.rs/ricochet/exec-env-r:4.4-alpine"
-os = "alpine-3.21"
+[image.r-44]
+image = "docker.io/ricochetrs/r-alpine:4.4"
+os = "alpine-3.23"
 arch = ["linux/amd64", "linux/arm64"]
 r = [
-  { version = "4.4.1", bin = "/opt/R/4.4.1/bin/R" },
-  { version = "4.4.2", bin = "/opt/R/4.4.2/bin/R" },
+  { version = "4.4.3", bin = "/usr/bin/R" },
 ]
 
 [image.python-default]
-image = "reg.ricochet.rs/ricochet/exec-env-python:3.12"
+image = "docker.io/ricochetrs/python-ubuntu:3.12"
 os = "ubuntu-22.04"
 arch = ["linux/amd64", "linux/arm64"]
+description = "Default Python 3.12 environment (Ubuntu)"
 python = [
-  { version = "3.12.0", bin = "/usr/local/bin/python3" },
+  { version = "3.12", bin = "/usr/local/bin/python3" },
 ]
 ```
 
@@ -160,6 +168,8 @@ pvc_cache_name = "ricochet-cache"
 image_pull_policy = "IfNotPresent"
 ```
 
+The same [`ricochet-exec-env.toml`](#exec-env-config) format applies, and the [official exec-env images](https://github.com/ricochet-rs/exec-envs) work unchanged as Pod images — they're built multi-arch (amd64/arm64) and ship with the same runtimes used by the container backend.
+
 See [Kubernetes installation](/dev/admin/installation/3-kubernetes/) for cluster prerequisites, Helm chart values, and PVC sizing guidance.
 
 ## Known issues
diff --git a/src/content/docs/dev/admin/installation/2-container.mdx b/src/content/docs/dev/admin/installation/2-container.mdx
index 3a4dfc4..6f83e07 100644
--- a/src/content/docs/dev/admin/installation/2-container.mdx
+++ b/src/content/docs/dev/admin/installation/2-container.mdx
@@ -81,7 +81,7 @@ Set in `ricochet-config.toml`:
   Mount the host data directory into the ricochet-server container at the **same path** used in the config, or sibling containers will mount empty directories and content will fail to start.
 </Aside>
 
-See the [execution backend reference](/dev/admin/configuration/execution-backend/#reachability) for `proxy_host` alternatives (`--network host`, explicit host IP) and the full field reference.
+See the [execution backend reference](/dev/admin/configuration/execution-backend/#ricochet-server-in-a-container-sibling-containers) for `proxy_host` alternatives (`--network host`, explicit host IP) and the full field reference.
 
 ### Kubernetes backend
 

From fc3486b735169191591de29e2943a542aa209938 Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 16:37:07 +0200
Subject: [PATCH 6/8] fixes

---
 .../docs/dev/admin/configuration/execution-backend.mdx   | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index cae8818..06d33d1 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -99,10 +99,10 @@ r = [
 ]
 
 [image.python-default]
-image = "docker.io/ricochetrs/python-ubuntu:3.12"
-os = "ubuntu-22.04"
+image = "docker.io/ricochetrs/python-ubuntu:3.13"
+os = "ubuntu-26.04"
 arch = ["linux/amd64", "linux/arm64"]
-description = "Default Python 3.12 environment (Ubuntu)"
+description = "Default Python 3.13 environment (Ubuntu)"
 python = [
   { version = "3.12", bin = "/usr/local/bin/python3" },
 ]
@@ -186,6 +186,5 @@ See [Kubernetes installation](/dev/admin/installation/3-kubernetes/) for cluster
 
 <Aside type="note" title="Remote daemons not yet supported">
   ricochet currently only talks to a daemon on the same host as ricochet-server.
-  Remote daemon support is on the roadmap and requires TLS configuration plus a deliberate strategy for `content_path` / `cache_path` (bind mounts resolve on the daemon's host — shared NFS, named volumes, or per-content image baking).
-  Until then, use the Kubernetes backend for multi-host execution.
+  Remote daemon support is on the roadmap.
 </Aside>

From 47d75a2d7bf05a7652b523f39410decad18dbfb9 Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 16:40:34 +0200
Subject: [PATCH 7/8] docs(dev): restructure execution-backend and fix
 ricochet-server image
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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.
---
 .../admin/configuration/execution-backend.mdx | 19 ++++++++++++++-----
 .../dev/admin/installation/2-container.mdx    |  8 ++++----
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index 06d33d1..e2c37c3 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -110,9 +110,12 @@ python = [
 
 `r`, `python`, and `julia` arrays declare the interpreter versions present in the image and the path to their binaries — ricochet uses these to match a content item's required version against an available runtime.
 
-## Deployment scenarios
+### Deployment scenarios
 
-### ricochet-server via systemd (on the host)
+How ricochet-server itself is deployed shapes the container-backend setup.
+The ricochet-server install is covered on its own page — only the container-backend specifics are below.
+
+#### ricochet-server via systemd (on the host)
 
 Set up ricochet-server first — see [Host installation](/dev/admin/installation/1-host/).
 
@@ -122,7 +125,7 @@ Container-backend specifics:
 - The user running ricochet-server needs read/write access to the daemon socket (typically by adding it to the `docker` group, or running as root as the default systemd unit does).
 - `proxy_host` can stay at its default `localhost` since both processes share the host's network namespace.
 
-### ricochet-server in a container (sibling containers)
+#### ricochet-server in a container (sibling containers)
 
 Set up ricochet-server in a container first — see [Container installation](/dev/admin/installation/2-container/).
 
@@ -140,7 +143,7 @@ docker run -d \
   --add-host=host.docker.internal:host-gateway \
   -v /var/run/docker.sock:/var/run/docker.sock \
   -v /var/lib/ricochet:/var/lib/ricochet \
-  ghcr.io/ricochet-rs/ricochet-server:latest
+  docker.io/ricochetrs/ricochet-server:latest
 ```
 
 ```toml title="ricochet-config.toml (DooD)"
@@ -175,16 +178,22 @@ See [Kubernetes installation](/dev/admin/installation/3-kubernetes/) for cluster
 ## Known issues
 
 <Aside type="caution" title="Path mismatch is silent">
+  Applies to the [container backend](#container-backend) — most often in the [DooD scenario](#ricochet-server-in-a-container-sibling-containers) where ricochet-server's filesystem view differs from the host's.
+
   If `content_path` points to a path that does not exist on the host, the daemon still launches the spawned container — but bind-mounts the wrong (or empty) directory.
   Content items will appear to deploy but fail at runtime because their bundles are not visible.
   Verify `ls $content_path` works on the **host**, not just inside the ricochet-server container.
 </Aside>
 
-<Aside type="caution" title="Wrong `proxy_host` is silent too">
+<Aside type="caution" title="Wrong proxy_host is silent too">
+  Applies to the [container backend](#container-backend) in the [DooD scenario](#ricochet-server-in-a-container-sibling-containers) only — see [Field reference](#container-backend) for the `proxy_host` setting.
+
   If `proxy_host` resolves but does not actually reach the host (typo, wrong IP, missing `--add-host`), spawned content containers start and pass health checks at the container layer, but ricochet's reverse proxy gets a connection refused or timeout when it tries to route a request — surfacing as 502s in the UI.
 </Aside>
 
 <Aside type="note" title="Remote daemons not yet supported">
+  Applies to the [container backend](#container-backend). The [Kubernetes backend](#kubernetes-backend) is the supported path for multi-host execution today.
+
   ricochet currently only talks to a daemon on the same host as ricochet-server.
   Remote daemon support is on the roadmap.
 </Aside>
diff --git a/src/content/docs/dev/admin/installation/2-container.mdx b/src/content/docs/dev/admin/installation/2-container.mdx
index 6f83e07..9249dda 100644
--- a/src/content/docs/dev/admin/installation/2-container.mdx
+++ b/src/content/docs/dev/admin/installation/2-container.mdx
@@ -10,7 +10,7 @@ This is the same `ricochet-server` binary as the [host install](/dev/admin/insta
 ## Image
 
 ```
-ghcr.io/ricochet-rs/ricochet-server:<version>
+docker.io/ricochetrs/ricochet-server:<version>
 ```
 
 Tags follow the ricochet release version (e.g. `v0.7.3`).
@@ -39,7 +39,7 @@ docker run -d \
   --name ricochet-server \
   -p 6188:6188 \
   -v /var/lib/ricochet:/var/lib/ricochet \
-  ghcr.io/ricochet-rs/ricochet-server:latest
+  docker.io/ricochetrs/ricochet-server:latest
 ```
 
 Place your `ricochet-config.toml` at `/var/lib/ricochet/ricochet-config.toml` on the host.
@@ -67,7 +67,7 @@ docker run -d \
   --add-host=host.docker.internal:host-gateway \
   -v /var/run/docker.sock:/var/run/docker.sock \
   -v /var/lib/ricochet:/var/lib/ricochet \
-  ghcr.io/ricochet-rs/ricochet-server:latest
+  docker.io/ricochetrs/ricochet-server:latest
 ```
 
 Set in `ricochet-config.toml`:
@@ -92,7 +92,7 @@ For multi-node setups, do not run ricochet-server as a standalone container —
 ```yaml title="compose.yml"
 services:
   ricochet-server:
-    image: ghcr.io/ricochet-rs/ricochet-server:latest
+    image: docker.io/ricochetrs/ricochet-server:latest
     container_name: ricochet-server
     ports:
       - "6188:6188"

From c8ce98025ad27214cf846ddab56931b253131f8e Mon Sep 17 00:00:00 2001
From: pat-s <patrick.schratz@gmail.com>
Date: Thu, 21 May 2026 16:42:22 +0200
Subject: [PATCH 8/8] docs(dev): align python exec-env example to 3.13 across
 image, description, and runtime

---
 src/content/docs/dev/admin/configuration/execution-backend.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/dev/admin/configuration/execution-backend.mdx b/src/content/docs/dev/admin/configuration/execution-backend.mdx
index e2c37c3..1caaa53 100644
--- a/src/content/docs/dev/admin/configuration/execution-backend.mdx
+++ b/src/content/docs/dev/admin/configuration/execution-backend.mdx
@@ -104,7 +104,7 @@ os = "ubuntu-26.04"
 arch = ["linux/amd64", "linux/arm64"]
 description = "Default Python 3.13 environment (Ubuntu)"
 python = [
-  { version = "3.12", bin = "/usr/local/bin/python3" },
+  { version = "3.13", bin = "/usr/local/bin/python3" },
 ]
 ```