Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

docs: document container image and registry configuration (#2186)

Kamryn Schock36a187dae882
diff --git a/.env.example b/.env.example
index 9f9c2fe6a..e0ec1b965 100644
--- a/.env.example
+++ b/.env.example
@@ -342,6 +342,38 @@ NEXT_ALLOWED_DEV_ORIGINS=
# but can be pinned here to lock the deployment to a specific version when running OpenRAG with Make commands.
OPENRAG_VERSION=latest
+# Container image and registry configuration.
+# By default OpenRAG pulls its images from Docker Hub (docker.io/langflowai).
+# Set these to pull from a private registry or internal mirror instead, e.g. in
+# an enterprise or air-gapped environment. Mirror the images first — see
+# https://docs.openr.ag/docker#private-registry
+#
+# Registry host for the OpenRAG-owned images (openrag-backend, openrag-frontend,
+# openrag-langflow, openrag-opensearch). Hostname only: no scheme, no trailing
+# slash. Include the port if non-standard, e.g. registry.example.com:5000.
+# Note: setting this to anything other than docker.io disables the TUI's
+# Docker Hub update check (no upgrade or up-to-date notification is shown).
+# Default: docker.io
+# IMAGE_REGISTRY=registry.example.com
+
+# Organization / namespace holding the OpenRAG-owned images within
+# IMAGE_REGISTRY. Images resolve to IMAGE_REGISTRY/IMAGE_ORG/<image>:<tag>.
+# Default: langflowai
+# IMAGE_ORG=platform-team
+
+# Overrides the tag for all OpenRAG-owned images. Takes precedence over
+# OPENRAG_VERSION above; falls back to OPENRAG_VERSION, then 'latest'.
+# Use this when your mirror re-tags images differently from OpenRAG releases.
+# Default: unset
+# OPENRAG_IMAGE_TAG=0.6.4
+
+# Registry host for the OpenSearch Dashboards image only, so you can mirror it
+# without redirecting the OpenRAG-owned images. The repository path and tag are
+# fixed, so the mirrored image must exist at
+# <DASHBOARDS_REGISTRY>/opensearchproject/opensearch-dashboards:3.6.0
+# Default: docker.io
+# DASHBOARDS_REGISTRY=registry.example.com
+
# Docker Compose project name. Change this to run multiple instances of OpenRAG alongside each other.
COMPOSE_PROJECT_NAME=openrag
diff --git a/docs/docs/get-started/docker.mdx b/docs/docs/get-started/docker.mdx
index 8a1272957..e78ebaab2 100644
--- a/docs/docs/get-started/docker.mdx
+++ b/docs/docs/get-started/docker.mdx
@@ -122,7 +122,71 @@ The following variables are required or recommended:
8. Save your `.env` file.
-## Start services
+## Deploy from a private registry {#private-registry}
+
+By default, OpenRAG pulls its container images from Docker Hub.
+If your environment can't reach Docker Hub, or your organization requires images to be served from an approved registry, mirror the OpenRAG images to your own registry and then point your deployment at it.
+
+This is only supported for self-managed deployments. For Kubernetes deployments, configure the registry through the Helm chart's `global.imageRegistry`, `global.imageTag`, and `global.imagePullSecrets` values instead.
+
+1. Mirror the following images to your registry.
+
+ The OpenRAG containers use five images. Replace `VERSION` with the OpenRAG version you intend to deploy, such as `0.6.4`:
+
+ | Source image | Mirrored path must be |
+ |---|---|
+ | `docker.io/langflowai/openrag-backend:VERSION` | `REGISTRY/ORG/openrag-backend:TAG` |
+ | `docker.io/langflowai/openrag-frontend:VERSION` | `REGISTRY/ORG/openrag-frontend:TAG` |
+ | `docker.io/langflowai/openrag-langflow:VERSION` | `REGISTRY/ORG/openrag-langflow:TAG` |
+ | `docker.io/langflowai/openrag-opensearch:VERSION` | `REGISTRY/ORG/openrag-opensearch:TAG` |
+ | `docker.io/opensearchproject/opensearch-dashboards:3.6.0` | `DASHBOARDS_REGISTRY/opensearchproject/opensearch-dashboards:3.6.0` |
+
+ The first four images resolve from `IMAGE_REGISTRY` and `IMAGE_ORG`, so you can mirror them into any organization you control.
+ The OpenSearch Dashboards image resolves from `DASHBOARDS_REGISTRY` only, so you must preserve the `opensearchproject/opensearch-dashboards` path and the `3.6.0` tag when you mirror it.
+
+ :::tip
+ The OpenRAG images are multi-architecture manifests.
+ Copy them with a tool that preserves every architecture, such as `skopeo copy --all` or `docker buildx imagetools create`.
+ A plain `docker pull` followed by `docker push` copies only the architecture of the machine that ran it, which produces images that fail to start on other platforms.
+ :::
+
+2. If your registry requires authentication, sign in on the host that runs the containers:
+
+ ```bash title="Docker"
+ docker login registry.example.com
+ ```
+
+ ```bash title="Podman"
+ podman login registry.example.com
+ ```
+
+ OpenRAG checks that each image exists in the registry before it pulls, and that check uses your local credentials.
+ Signing in first prevents the deployment from failing with an authentication error.
+
+ If your `IMAGE_REGISTRY` and `DASHBOARDS_REGISTRY` are different, you might sign in to both registry hosts.
+
+3. In your `.env` file, set the [container image and registry variables](/reference/configuration#container-image-and-registry-settings) for your registry:
+
+ ```env
+ IMAGE_REGISTRY=registry.example.com
+ IMAGE_ORG=platform-team
+ DASHBOARDS_REGISTRY=registry.example.com
+
+ # Set the tag your mirrored images use.
+ OPENRAG_IMAGE_TAG=0.6.4
+ ```
+
+ Set `IMAGE_REGISTRY` to a hostname without a scheme or trailing slash, and include the port if your registry uses a non-standard one, such as `registry.example.com:5000`.
+
+ Set `OPENRAG_IMAGE_TAG` if your mirrored images are tagged differently from the OpenRAG release versions.
+ It takes precedence over `OPENRAG_VERSION`.
+ If neither variable is set, OpenRAG pulls the `latest` tag, which many private registries don't populate.
+
+4. Save your `.env` file, and then continue with [Start services](#start-services).
+
+If the containers fail to start with an image pull error, see [Container image pull failures](/support/troubleshoot#image-pull-failures).
+
+## Start services {#start-services}
1. To use the default Docling Serve implementation, start `docling serve` on port 5001 on the host machine using the included script:
diff --git a/docs/docs/get-started/upgrade.mdx b/docs/docs/get-started/upgrade.mdx
index 2dbaea61a..886e08f1b 100644
--- a/docs/docs/get-started/upgrade.mdx
+++ b/docs/docs/get-started/upgrade.mdx
@@ -111,7 +111,10 @@ The commands to upgrade the package depend on how you installed OpenRAG.
<PartialExportFlows />
-2. Fetch and apply the latest container images while preserving your OpenRAG data:
+2. If you [pull images from a private registry](/docker#private-registry), mirror the new version's images to your registry first, and then set `OPENRAG_IMAGE_TAG` or `OPENRAG_VERSION` in your `.env` file to the new tag.
+ The pull in the next step fails if the new images aren't present in your registry yet.
+
+3. Fetch and apply the latest container images while preserving your OpenRAG data:
```bash title="Docker"
docker compose pull
@@ -125,10 +128,14 @@ The commands to upgrade the package depend on how you installed OpenRAG.
By default, OpenRAG's `docker-compose` files pull the latest container images.
To use a specific earlier version, you set `OPENRAG_VERSION` in your `.env` file to the desired image tag, and then run OpenRAG with `docker compose`, `podman compose`, or [`make`](/support/contribute) commands.
- Overriding the `OPENRAG_VERSION` is only possible with self-managed deployments.
+ Overriding the image tag is only possible with self-managed deployments.
This allows you to pin your OpenRAG containers to a specific version rather than deploying the latest version.
-3. After the containers start, access the OpenRAG application at `http://localhost:3000`.
+ You can also set [`OPENRAG_IMAGE_TAG`](/reference/configuration#container-image-and-registry-settings), which overrides the image tag for all OpenRAG images and takes precedence over `OPENRAG_VERSION`.
+ If both variables are set, OpenRAG uses `OPENRAG_IMAGE_TAG`, so check that variable first if the containers don't start at the version you expect.
+ `OPENRAG_IMAGE_TAG` is primarily useful when you [pull images from a private registry](/docker#private-registry) that tags them differently from the OpenRAG releases.
+
+4. After the containers start, access the OpenRAG application at `http://localhost:3000`.
## See also
diff --git a/docs/docs/reference/configuration.mdx b/docs/docs/reference/configuration.mdx
index a69bdeb18..4c88e5a44 100644
--- a/docs/docs/reference/configuration.mdx
+++ b/docs/docs/reference/configuration.mdx
@@ -158,6 +158,29 @@ Configure OpenSearch database authentication.
| `LANGFLOW_OPENSEARCH_HOST` | Not set | By default, OpenRAG passes the `OPENSEARCH_HOST` value to Langflow. Use the `LANGFLOW_OPENSEARCH_*` variables to set a different OpenSearch endpoint for Langflow specifically. OpenRAG itself still uses the `OPENSEARCH_HOST` value. |
| `LANGFLOW_OPENSEARCH_PORT` | Not set | By default, OpenRAG passes the `OPENSEARCH_PORT` value to Langflow. Use the `LANGFLOW_OPENSEARCH_*` variables to set a different OpenSearch endpoint for Langflow specifically. OpenRAG itself still uses the `OPENSEARCH_PORT` value. |
+## Container image and registry settings {#container-image-and-registry-settings}
+
+By default, OpenRAG pulls its container images from Docker Hub under the `langflowai` organization.
+Use these variables to pull images from a private registry or an internal mirror instead, such as in an enterprise or air-gapped environment.
+
+For a complete walkthrough, including how to mirror the images, see [Deploy OpenRAG from a private registry](/docker#private-registry).
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `IMAGE_REGISTRY` | `docker.io` | Registry host for the OpenRAG-owned images (`openrag-backend`, `openrag-frontend`, `openrag-langflow`, and `openrag-opensearch`). Set this to your registry hostname, and include the port if your registry uses a non-standard one, such as `registry.example.com:5000`. Don't include a scheme (`https://`) or a trailing slash. This variable doesn't affect the OpenSearch Dashboards image; use `DASHBOARDS_REGISTRY` for that image. |
+| `IMAGE_ORG` | `langflowai` | Organization or namespace that contains the OpenRAG-owned images within `IMAGE_REGISTRY`. Together, these variables form the repository path `IMAGE_REGISTRY/IMAGE_ORG/IMAGE_NAME`. For example, `IMAGE_REGISTRY=registry.example.com` and `IMAGE_ORG=platform-team` resolves the backend image to `registry.example.com/platform-team/openrag-backend`. |
+| `OPENRAG_IMAGE_TAG` | Not set | Overrides the image tag applied to all OpenRAG-owned images. When set, this variable takes precedence over `OPENRAG_VERSION`. When it isn't set, OpenRAG falls back to `OPENRAG_VERSION`, and then to `latest`. Use this variable when your mirror re-tags images and the tags don't match the OpenRAG release versions. |
+| `DASHBOARDS_REGISTRY` | `docker.io` | Registry host for the OpenSearch Dashboards image only. This lets you point Dashboards at a mirror without redirecting the OpenRAG-owned images. The repository path and tag within the registry are fixed, so the mirrored image must be available at `DASHBOARDS_REGISTRY/opensearchproject/opensearch-dashboards:3.6.0`. |
+
+:::important
+These variables are read by Docker Compose, so they apply to [self-managed deployments](/docker).
+Terminal-managed deployments read them from `~/.openrag/tui/.env`, where they determine which images the terminal session treats as OpenRAG-owned when it pulls or cleans up images.
+
+Setting `IMAGE_REGISTRY` to a host other than `docker.io` also disables the terminal session's update check, because that check queries the Docker Hub API. The **Status** page reports neither an available upgrade nor an up-to-date confirmation. Track new releases through your registry or the [OpenRAG releases page](https://github.com/langflow-ai/openrag/releases) instead.
+
+Kubernetes deployments don't use these variables. The Helm charts in [`kubernetes/helm`](https://github.com/langflow-ai/openrag/tree/main/kubernetes/helm) configure images through their own `global.imageRegistry`, `global.imageTag`, and `global.imagePullSecrets` values. Note that the chart's `global.imageRegistry` value holds the organization (`langflowai` by default), which is the equivalent of `IMAGE_ORG` rather than `IMAGE_REGISTRY`.
+:::
+
## System settings
Configure general system components, session management, and logging.
@@ -165,7 +188,7 @@ Configure general system components, session management, and logging.
| Variable | Default | Description |
|----------|---------|-------------|
| `FRONTEND_PORT` | `3000` | Host port for the OpenRAG frontend web interface. Change this if port 3000 is already in use on your system. |
-| `OPENRAG_VERSION` | `latest` | The version of the OpenRAG Docker images to run. For more information, see [Upgrade OpenRAG](/upgrade) |
+| `OPENRAG_VERSION` | `latest` | The version of the OpenRAG Docker images to run. If [`OPENRAG_IMAGE_TAG`](#container-image-and-registry-settings) is set, it takes precedence over this variable. For more information, see [Upgrade OpenRAG](/upgrade) |
| `NEXT_ALLOWED_DEV_ORIGINS` | `http://localhost:3000` | Only used when [running OpenRAG in development mode](/support/contribute). Accepts a comma-separated list of hostnames to allow additional origins to make requests to the Next.js development server. |
| `MAX_WORKERS` | `min(4, CPU_COUNT // 2)` | Number of Backend worker processes for concurrent request handling. Be mindful of hardware limitations to avoid overtaxing system resources. |
| `LANGFLOW_WORKERS` | `1` | Number of Langflow worker processes for concurrent request handling. Be mindful of hardware limitations to avoid overtaxing system resources. |
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 03edc4fc2..ced0e976f 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -17,7 +17,7 @@ If you are installing OpenRAG on macOS, and the installation fails with `unable
open "/Applications/Python 3.13/Install Certificates.command"
```
-## No container runtime found, or Docker/Podman not ready
+## No container runtime found, or Docker/Podman not ready {#no-container-runtime-found-or-dockerpodman-not-ready}
When you start OpenRAG, `No container runtime found` and `Docker/Podman not ready` errors indicate that OpenRAG cannot find or start a running Docker or Podman machine to run the OpenRAG containers.
@@ -30,6 +30,42 @@ Either run `podman machine start` or a similar command, or start the Docker/Podm
For Linux environments, you can find more troubleshooting advice in the [Podman installation documentation](https://podman.io/docs/installation#installing-on-linux) and the [Docker installation documentation](https://docs.docker.com/engine/install/).
+## Container image pull failures {#image-pull-failures}
+
+Before pulling a missing image, OpenRAG verifies that the image exists in its registry.
+If the check fails, OpenRAG stops rather than attempting the pull, and reports an error in the following form:
+
+```
+ERROR: Cannot pull image 'REGISTRY/ORG/IMAGE:TAG': REASON
+```
+
+The reason identifies which part of your [image and registry configuration](/reference/configuration#container-image-and-registry-settings) is wrong:
+
+| Reason | Cause | Resolution |
+|---|---|---|
+| `Image 'IMAGE' not found in registry` | If the registry is reachable and your credentials are valid, then the registry has no image at the given repository path and tag. | Verify that `IMAGE_ORG` matches the organization in your registry, and that the tag from `OPENRAG_IMAGE_TAG` or `OPENRAG_VERSION` exists. This commonly occurs when neither tag variable is set, because OpenRAG then requests the `latest` tag, which many private registries don't populate. |
+| `Authentication failure accessing 'IMAGE'` | The registry rejected the request with a `401` or `403`. | Sign in to the registry with `docker login REGISTRY` or `podman login REGISTRY` on the host that runs the containers, then retry. If you are already signed in, confirm that the account can read the repository, because some registries return an authentication error rather than a not-found error for repositories you can't access. |
+| `Registry unreachable for 'IMAGE'` | The registry host couldn't be reached because of a DNS, network, or TLS failure. | Check that the hostname in `IMAGE_REGISTRY` resolves and is reachable from the host. If your registry uses a private certificate authority, add the certificate to your container runtime's trust store. If your registry listens on a non-standard port, include it in the variable, such as `registry.example.com:5000`. |
+| `Timed out contacting registry for 'IMAGE'` | The registry didn't respond within 30 seconds. | Check for a proxy or firewall that silently drops the connection, and confirm the registry is healthy. |
+| `Image reference 'IMAGE' could not be parsed`, or `Image reference is malformed` | The resolved image reference isn't a valid image name. | Remove any scheme (`https://`) or trailing slash from `IMAGE_REGISTRY` and `IMAGE_ORG`, and make sure neither variable contains spaces or is set to an empty value. |
+| `Container runtime 'docker' not found on PATH` | The container runtime executable is unavailable. | See [No container runtime found, or Docker/Podman not ready](#no-container-runtime-found-or-dockerpodman-not-ready). |
+
+This check only covers the OpenRAG-owned images.
+The OpenSearch Dashboards image isn't validated in advance, so an incorrect `DASHBOARDS_REGISTRY` value doesn't produce one of the errors above.
+Instead, the deployment fails later with a pull error from Docker or Podman.
+Because the repository path and tag for that image are fixed, confirm that the mirrored image is available at `DASHBOARDS_REGISTRY/opensearchproject/opensearch-dashboards:3.6.0`, and make sure `DASHBOARDS_REGISTRY` is set correctly.
+
+For instructions on mirroring the images, see [Deploy OpenRAG from a private registry](/docker#private-registry).
+
+## The terminal session doesn't report available upgrades {#no-upgrade-check-with-private-registry}
+
+The terminal session checks for new OpenRAG versions by querying the Docker Hub API.
+If you set `IMAGE_REGISTRY` to any host other than `docker.io`, this check can't run.
+
+The **Status** page then reports neither an available upgrade nor an up-to-date confirmation, and no notification appears.
+This is expected, and it doesn't indicate a problem with your deployment.
+To track new releases, monitor your own registry or the [OpenRAG releases page](https://github.com/langflow-ai/openrag/releases), and then [upgrade](/upgrade) by mirroring the new images and updating `OPENRAG_IMAGE_TAG` or `OPENRAG_VERSION`.
+
## Container out of memory errors {#container-out-of-memory-errors}
If you encounter container memory errors, try the following: