feat(ci): consume ECR pull-through cache for CI base images (#11600)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-10-19 01:50:51 -05:00 · 2026-06-02 21:24:46 +00:00
1 parent 5f282fd984
commit 033938f78f
@@ -1,4 +1,14 @@
-FROM ubuntu:26.04@sha256:cc925e589b7543b910fea57a240468940003fbfc0515245a495dd0ad8fe7cef1
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits.
+ARG BASE_IMAGE_REGISTRY=docker.io
+
+# bun + node binary sources. Pinned via the registry prefix in their own stages because buildx
+# rejects variable expansion directly in `COPY --from=` -- the ARG is only expandable in a FROM.
+FROM ${BASE_IMAGE_REGISTRY}/oven/bun:1@sha256:e10577f0db68676a7024391c6e5cb4b879ebd17188ab750cf10024a6d700e5c4 AS bun_source
+FROM ${BASE_IMAGE_REGISTRY}/library/node:24.16.0-trixie-slim@sha256:05c08ce4291e9a58f59456a7985176defb12cdd42271f35ff81a3e167ea61d4c AS node_source
+
+FROM ${BASE_IMAGE_REGISTRY}/library/ubuntu:26.04@sha256:cc925e589b7543b910fea57a240468940003fbfc0515245a495dd0ad8fe7cef1

 RUN apt-get update && apt-get install -y --no-install-recommends \
  build-essential \
@@ -48,8 +58,8 @@ RUN ln -sf "$(which fdfind)" /usr/local/bin/fd
 # (cmake, libxmlsec1-dev, pkg-config, postgresql-client).
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/

-# Install bun (JavaScript package manager)
-COPY --from=oven/bun:1@sha256:e10577f0db68676a7024391c6e5cb4b879ebd17188ab750cf10024a6d700e5c4 /usr/local/bin/bun /usr/local/bin/bun
+# Install bun (JavaScript package manager) from the bun_source stage defined at the top.
+COPY --from=bun_source /usr/local/bin/bun /usr/local/bin/bun
 RUN ln -s /usr/local/bin/bun /usr/local/bin/bunx

 # Install Node.js. Bun is the JS package manager, but Playwright's e2e test
@@ -59,13 +69,13 @@ RUN ln -s /usr/local/bin/bun /usr/local/bin/bunx
 # The chromium browser binary is installed at test time (web global-setup), not
 # baked here, so its version tracks web/package.json's floating @playwright/test.
 #
-# Copied from the official node image (digest-pinned like bun above) instead of
-# fetched from nodejs.org, so a compromised mirror or MITM can't swap the binary
-# and buildkit resolves the right arch from the manifest list. Keep both COPY
-# refs in sync when bumping the version. npm/npx are scripts under
-# node_modules/npm; recreate their PATH symlinks since we copy the bare binary.
-COPY --from=node:24.16.0-trixie-slim@sha256:05c08ce4291e9a58f59456a7985176defb12cdd42271f35ff81a3e167ea61d4c /usr/local/bin/node /usr/local/bin/node
-COPY --from=node:24.16.0-trixie-slim@sha256:05c08ce4291e9a58f59456a7985176defb12cdd42271f35ff81a3e167ea61d4c /usr/local/lib/node_modules /usr/local/lib/node_modules
+# Copied from the official node image (digest-pinned in the node_source stage at the
+# top, routed through BASE_IMAGE_REGISTRY) instead of fetched from nodejs.org, so a
+# compromised mirror or MITM can't swap the binary and buildkit resolves the right arch
+# from the manifest list. npm/npx are scripts under node_modules/npm; recreate their
+# PATH symlinks since we copy the bare binary.
+COPY --from=node_source /usr/local/bin/node /usr/local/bin/node
+COPY --from=node_source /usr/local/lib/node_modules /usr/local/lib/node_modules
 RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
  && ln -s ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx \
  && node --version
@@ -17,11 +17,8 @@ inputs:
  run-id:
    description: "GitHub run ID used in output image tag"
    required: true
-  docker-username:
-    description: "Docker Hub username"
-    required: true
-  docker-token:
-    description: "Docker Hub token"
+  ecr-registry:
+    description: "ECR registry host for the Docker Hub pull-through cache (the ECR_REGISTRY repo variable)"
    required: true
  docker-no-cache:
    description: "Set to 'true' to disable docker build cache"
@@ -48,11 +45,10 @@ runs:
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # ratchet:docker/setup-buildx-action@v3

-    - name: Login to Docker Hub
-      uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+    - name: Log in to ECR pull-through cache
+      uses: ./.github/actions/login-ecr-pullthrough-cache
      with:
-        username: ${{ inputs.docker-username }}
-        password: ${{ inputs.docker-token }}
+        ecr-registry: ${{ inputs.ecr-registry }}

    - name: Build and push Backend Docker image
      uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # ratchet:docker/build-push-action@v6
@@ -60,12 +56,14 @@ runs:
        context: ./backend
        file: ./backend/Dockerfile
        push: true
+        build-args: |
+          BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
        tags: ${{ inputs.runs-on-ecr-cache }}:nightly-llm-it-backend-${{ inputs.run-id }}
        cache-from: |
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:backend-cache-${{ inputs.github-sha }}
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:backend-cache-${{ steps.format-branch.outputs.cache-suffix }}
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:backend-cache
-          type=registry,ref=onyxdotapp/onyx-backend:latest
+          type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-backend:latest
        cache-to: |
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:backend-cache-${{ inputs.github-sha }},mode=max
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:backend-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -21,11 +21,8 @@ inputs:
    description: "Prefix for the output image tag (the full tag will be <prefix>-<run-id>)"
    required: false
    default: "nightly-llm-it-devcontainer"
-  docker-username:
-    description: "Docker Hub username"
-    required: true
-  docker-token:
-    description: "Docker Hub token"
+  ecr-registry:
+    description: "ECR registry host for the Docker Hub pull-through cache (the ECR_REGISTRY repo variable)"
    required: true
  docker-no-cache:
    description: "Set to 'true' to disable docker build cache"
@@ -52,11 +49,10 @@ runs:
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # ratchet:docker/setup-buildx-action@v3

-    - name: Login to Docker Hub
-      uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+    - name: Log in to ECR pull-through cache
+      uses: ./.github/actions/login-ecr-pullthrough-cache
      with:
-        username: ${{ inputs.docker-username }}
-        password: ${{ inputs.docker-token }}
+        ecr-registry: ${{ inputs.ecr-registry }}

    - name: Build and push Devcontainer Docker image
      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -64,12 +60,14 @@ runs:
        context: .devcontainer
        file: .devcontainer/Dockerfile
        push: true
+        build-args: |
+          BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
        tags: ${{ inputs.runs-on-ecr-cache }}:${{ inputs.tag-prefix }}-${{ inputs.run-id }}
        cache-from: |
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:devcontainer-cache-${{ inputs.github-sha }}
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:devcontainer-cache-${{ steps.format-branch.outputs.cache-suffix }}
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:devcontainer-cache
-          type=registry,ref=onyxdotapp/onyx-devcontainer:latest
+          type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-devcontainer:latest
        cache-to: |
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:devcontainer-cache-${{ inputs.github-sha }},mode=max
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:devcontainer-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -17,11 +17,8 @@ inputs:
  run-id:
    description: "GitHub run ID used in output image tag"
    required: true
-  docker-username:
-    description: "Docker Hub username"
-    required: true
-  docker-token:
-    description: "Docker Hub token"
+  ecr-registry:
+    description: "ECR registry host for the Docker Hub pull-through cache (the ECR_REGISTRY repo variable)"
    required: true
 runs:
  using: "composite"
@@ -44,11 +41,10 @@ runs:
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # ratchet:docker/setup-buildx-action@v3

-    - name: Login to Docker Hub
-      uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+    - name: Log in to ECR pull-through cache
+      uses: ./.github/actions/login-ecr-pullthrough-cache
      with:
-        username: ${{ inputs.docker-username }}
-        password: ${{ inputs.docker-token }}
+        ecr-registry: ${{ inputs.ecr-registry }}

    - name: Build and push Model Server Docker image
      uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # ratchet:docker/build-push-action@v6
@@ -56,12 +52,14 @@ runs:
        context: ./backend
        file: ./backend/Dockerfile.model_server
        push: true
+        build-args: |
+          BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
        tags: ${{ inputs.runs-on-ecr-cache }}:nightly-llm-it-model-server-${{ inputs.run-id }}
        cache-from: |
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:model-server-cache-${{ inputs.github-sha }}
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }}
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:model-server-cache
-          type=registry,ref=onyxdotapp/onyx-model-server:latest
+          type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-model-server:latest
        cache-to: |
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:model-server-cache-${{ inputs.github-sha }},mode=max
          type=registry,ref=${{ inputs.runs-on-ecr-cache }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -0,0 +1,52 @@
+name: "Login to ECR pull-through cache"
+description: >
+  Authenticates Docker to the ECR Docker Hub pull-through cache using the runner's IAM
+  instance role, and exports BASE_IMAGE_REGISTRY so `docker compose`, buildx, and bake pull
+  base images through the cache (<account>.dkr.ecr.<region>.amazonaws.com/docker-hub) instead
+  of directly from Docker Hub, avoiding "Unauthenticated users" rate limits.
+
+  Requires a RunsOn runner whose IAM instance role grants ECR pull access to docker-hub/*
+  (provisioned in our infra-as-code). No Docker Hub PAT and no AWS OIDC role are needed.
+
+inputs:
+  ecr-registry:
+    description: "ECR registry host, e.g. <account>.dkr.ecr.us-east-2.amazonaws.com (set the ECR_REGISTRY repo variable)."
+    required: true
+  region:
+    description: "AWS region of the ECR registry."
+    required: false
+    default: "us-east-2"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Log in to Amazon ECR pull-through cache
+      shell: bash
+      env:
+        ECR_REGISTRY: ${{ inputs.ecr-registry }}
+        AWS_REGION: ${{ inputs.region }}
+      # BASE_IMAGE_REGISTRY is derived from the admin-set ECR_REGISTRY repo variable (a trusted
+      # hostname), not from attacker-controllable input, so the GITHUB_ENV write is safe.
+      run: | # zizmor: ignore[github-env]
+        if [ -z "${ECR_REGISTRY}" ]; then
+          echo "::error::ecr-registry input is empty. Set the ECR_REGISTRY repository variable to <account>.dkr.ecr.${AWS_REGION}.amazonaws.com." >&2
+          exit 1
+        fi
+        # Redact the registry host (which embeds the AWS account ID) from this job's logs:
+        # vars.* are not auto-masked the way secrets.* are, and docker compose / buildx echo the
+        # full image reference of every base image they pull. add-mask is per-job, so registering
+        # it here covers every job that uses this action.
+        echo "::add-mask::${ECR_REGISTRY}"
+        # The docker-hub/* pull-through-cache permissions are granted to the RunsOn EC2 instance
+        # role, NOT to any OIDC/static credentials a job might also configure. Clear ambient AWS
+        # credential and endpoint-override env vars so the CLI falls back to IMDS (the instance
+        # role) and the real ECR endpoint for this one call -- some jobs (e.g. craft) set static
+        # creds and point AWS_ENDPOINT_URL at an in-cluster MinIO, which would otherwise misdirect
+        # get-login-password.
+        env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY -u AWS_SESSION_TOKEN \
+            -u AWS_ENDPOINT_URL -u AWS_ENDPOINT_URL_ECR \
+          aws ecr get-login-password --region "${AWS_REGION}" \
+          | docker login --username AWS --password-stdin "${ECR_REGISTRY}"
+        # Consumed by docker-compose image interpolation (${BASE_IMAGE_REGISTRY:-docker.io}),
+        # the Dockerfiles' BASE_IMAGE_REGISTRY ARG, and docker-bake.hcl's matching variable.
+        echo "BASE_IMAGE_REGISTRY=${ECR_REGISTRY}/docker-hub" >> "${GITHUB_ENV}"
@@ -28,6 +28,7 @@ on:
      - "backend/tests/external_dependency_unit/craft/conftest.py"
      - ".github/workflows/pr-craft-k8s-tests.yml"
      - ".github/actions/setup-python-and-install-dependencies/**"
+      - ".github/actions/login-ecr-pullthrough-cache/**"
      - "deployment/docker_compose/docker-compose.yml"
      - "deployment/docker_compose/docker-compose.dev.yml"
      # Watch the whole chart, not just the templates we render — shared
@@ -118,11 +119,10 @@ jobs:
            backend/requirements/dev.txt
            backend/requirements/ee.txt

-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      # network=host so buildx (running in a container) can push to the
      # host's registry at localhost:5001.
@@ -136,7 +136,7 @@ jobs:
          docker run -d --restart=always \
            -p "127.0.0.1:${KIND_REGISTRY_PORT}:5000" \
            --name "${KIND_REGISTRY_NAME}" \
-            registry:2
+            "${BASE_IMAGE_REGISTRY:-docker.io}/library/registry:2"

      - name: Build and push sandbox image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -148,6 +148,7 @@ jobs:
          # so skip LibreOffice et al. to keep the CI image lean.
          build-args: |
            ENABLE_SKILLS=false
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          tags: localhost:5001/onyx-sandbox:ci
          push: true
          cache-from: type=gha,scope=craft-sandbox
@@ -162,6 +163,8 @@ jobs:
          platforms: linux/amd64
          tags: ${{ env.BACKEND_IMAGE }}
          push: true
+          build-args: |
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          cache-from: type=gha,scope=craft-backend
          cache-to: type=gha,scope=craft-backend,mode=max

@@ -41,6 +41,7 @@ jobs:
              - 'deployment/docker_compose/docker-compose.dev.yml'
              - '.github/workflows/pr-database-tests.yml'
              - '.github/actions/setup-python-and-install-dependencies/**'
+              - '.github/actions/login-ecr-pullthrough-cache/**'

  database-tests:
    needs: changes
@@ -74,13 +75,10 @@ jobs:
        run: |
          ods openapi all

-      # needed for pulling external images otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Start Docker containers
        working-directory: ./deployment/docker_compose
@@ -14,6 +14,7 @@ on:
      - ".github/workflows/pr-external-dependency-unit-tests.yml"
      - ".github/actions/setup-python-and-install-dependencies/**"
      - ".github/actions/setup-playwright/**"
+      - ".github/actions/login-ecr-pullthrough-cache/**"
      - "deployment/docker_compose/docker-compose.yml"
      - "deployment/docker_compose/docker-compose.dev.yml"
  push:
@@ -115,14 +116,10 @@ jobs:
      - name: Setup Playwright
        uses: ./.github/actions/setup-playwright

-      # needed for pulling Vespa, Redis, Postgres, and Minio images
-      # otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Create .env file for Docker Compose
        run: |
@@ -77,6 +77,7 @@ jobs:
              - '.github/workflows/pr-integration-tests.yml'
              - '.github/actions/setup-test-license/**'
              - '.github/actions/install-deps-and-generate-openapi-client/**'
+              - '.github/actions/login-ecr-pullthrough-cache/**'

  discover-test-dirs:
    # NOTE: Github-hosted runners have about 20s faster queue times and are preferred here.
@@ -160,14 +161,10 @@ jobs:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4

-      # needed for pulling Vespa, Redis, Postgres, and Minio images
-      # otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Build and push Model Server Docker image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -175,12 +172,14 @@ jobs:
          context: ./backend
          file: ./backend/Dockerfile.model_server
          push: true
+          build-args: |
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          tags: ${{ env.RUNS_ON_ECR_CACHE }}:integration-test-model-server-test-${{ github.run_id }}
          cache-from: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ github.event.pull_request.head.sha || github.sha }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache
-            type=registry,ref=onyxdotapp/onyx-model-server:latest
+            type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-model-server:latest
          cache-to: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ github.event.pull_request.head.sha || github.sha }},mode=max
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -221,11 +220,10 @@ jobs:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4

-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Build and push Devcontainer Docker image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -233,12 +231,14 @@ jobs:
          context: .devcontainer
          file: .devcontainer/Dockerfile
          push: true
+          build-args: |
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          tags: ${{ env.RUNS_ON_ECR_CACHE }}:integration-test-devcontainer-${{ github.run_id }}
          cache-from: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:devcontainer-cache-${{ github.event.pull_request.head.sha || github.sha }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:devcontainer-cache-${{ steps.format-branch.outputs.cache-suffix }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:devcontainer-cache
-            type=registry,ref=onyxdotapp/onyx-devcontainer:latest
+            type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-devcontainer:latest
          cache-to: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:devcontainer-cache-${{ github.event.pull_request.head.sha || github.sha }},mode=max
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:devcontainer-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -280,14 +280,10 @@ jobs:
        with:
          aws-oidc-role-arn: ${{ secrets.AWS_OIDC_ROLE_ARN }}

-      # needed for pulling Vespa, Redis, Postgres, and Minio images
-      # otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      # NOTE: Use pre-ping/null pool to reduce flakiness due to dropped connections
      # NOTE: don't need web server for integration tests
@@ -481,11 +477,10 @@ jobs:
        with:
          aws-oidc-role-arn: ${{ secrets.AWS_OIDC_ROLE_ARN }}

-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Create .env file for Onyx Lite Docker Compose
        run: |
@@ -584,11 +579,10 @@ jobs:
        with:
          persist-credentials: false

-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Start Docker containers for multi-tenant tests
        env:
@@ -102,6 +102,7 @@ jobs:
              - 'uv.lock'
              - '.github/workflows/pr-playwright-tests.yml'
              - '.github/actions/setup-test-license/**'
+              - '.github/actions/login-ecr-pullthrough-cache/**'

  build-web-image:
    needs: changes
@@ -139,13 +140,10 @@ jobs:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4

-      # needed for pulling external images otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Build and push Web Docker image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -155,11 +153,13 @@ jobs:
          platforms: linux/arm64
          tags: ${{ env.RUNS_ON_ECR_CACHE }}:playwright-test-web-${{ github.run_id }}
          push: true
+          build-args: |
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          cache-from: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-${{ github.event.pull_request.head.sha || github.sha }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-${{ steps.format-branch.outputs.cache-suffix }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache
-            type=registry,ref=onyxdotapp/onyx-web-server:latest
+            type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-web-server:latest
          cache-to: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-${{ github.event.pull_request.head.sha || github.sha }},mode=max
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:web-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -202,13 +202,10 @@ jobs:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4

-      # needed for pulling external images otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Build and push Backend Docker image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -218,11 +215,13 @@ jobs:
          platforms: linux/arm64
          tags: ${{ env.RUNS_ON_ECR_CACHE }}:playwright-test-backend-${{ github.run_id }}
          push: true
+          build-args: |
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          cache-from: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-${{ github.event.pull_request.head.sha || github.sha }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-${{ steps.format-branch.outputs.cache-suffix }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache
-            type=registry,ref=onyxdotapp/onyx-backend:latest
+            type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-backend:latest
          cache-to: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-${{ github.event.pull_request.head.sha || github.sha }},mode=max
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:backend-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -265,13 +264,10 @@ jobs:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4

-      # needed for pulling external images otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Build and push Model Server Docker image
        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # ratchet:docker/build-push-action@v7
@@ -281,11 +277,13 @@ jobs:
          platforms: linux/arm64
          tags: ${{ env.RUNS_ON_ECR_CACHE }}:playwright-test-model-server-${{ github.run_id }}
          push: true
+          build-args: |
+            BASE_IMAGE_REGISTRY=${{ env.BASE_IMAGE_REGISTRY }}
          cache-from: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ github.event.pull_request.head.sha || github.sha }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }}
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache
-            type=registry,ref=onyxdotapp/onyx-model-server:latest
+            type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-model-server:latest
          cache-to: |
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ github.event.pull_request.head.sha || github.sha }},mode=max
            type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
@@ -365,14 +363,10 @@ jobs:
          ONYX_WEB_SERVER_IMAGE=${ECR_CACHE}:playwright-test-web-${RUN_ID}
          EOF

-      # needed for pulling Vespa, Redis, Postgres, and Minio images
-      # otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Start Docker containers
        run: |
@@ -607,13 +601,10 @@ jobs:
          ONYX_WEB_SERVER_IMAGE=${ECR_CACHE}:playwright-test-web-${RUN_ID}
          EOF

-      # needed for pulling external images otherwise, we hit the "Unauthenticated users" limit
-      # https://docs.docker.com/docker-hub/usage/
-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Start Docker containers (lite)
        run: |
@@ -26,6 +26,7 @@ on:
      - "uv.lock"
      - ".github/workflows/pr-python-connector-tests.yml"
      - ".github/actions/build-backend-image/**"
+      - ".github/actions/login-ecr-pullthrough-cache/**"
  push:
    tags:
      - "v*.*.*"
@@ -34,7 +35,6 @@ on:
    - cron: "0 16 * * *"

 permissions:
-  id-token: write # Required for OIDC-based AWS credential exchange
  contents: read

 env:
@@ -77,19 +77,6 @@ jobs:
        with:
          persist-credentials: false

-      - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@ec61189d14ec14c8efccab744f656cffd0e33f37 # ratchet:aws-actions/configure-aws-credentials@v4
-        with:
-          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
-          aws-region: us-east-2
-
-      - name: Get Docker Hub credentials
-        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802 # ratchet:aws-actions/aws-secretsmanager-get-secrets@v2
-        with:
-          secret-ids: |
-            DOCKER_USERNAME, test/docker-username
-            DOCKER_TOKEN, test/docker-token
-
      - name: Build backend image
        uses: ./.github/actions/build-backend-image
        with:
@@ -98,12 +85,17 @@ jobs:
          pr-number: ${{ github.event.pull_request.number }}
          github-sha: ${{ github.sha }}
          run-id: ${{ github.run_id }}
-          docker-username: ${{ env.DOCKER_USERNAME }}
-          docker-token: ${{ env.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}
          docker-no-cache: ${{ vars.DOCKER_NO_CACHE == 'true' && 'true' || 'false' }}

  connectors-check:
    needs: build-backend-image
+    # id-token scoped to this job only -- it's the sole job that exchanges OIDC for AWS
+    # credentials (to fetch connector secrets); build-backend-image authenticates to ECR via
+    # the runner instance role instead.
+    permissions:
+      id-token: write
+      contents: read
    # See https://runs-on.com/runners/linux/
    runs-on:
      [
@@ -62,11 +62,10 @@ jobs:
          fi
          echo "cache-suffix=${CACHE_SUFFIX}" >> $GITHUB_OUTPUT

-      - name: Login to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121
+      - name: Log in to ECR pull-through cache
+        uses: ./.github/actions/login-ecr-pullthrough-cache
        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # ratchet:docker/setup-buildx-action@v4
@@ -82,7 +81,7 @@ jobs:
            model-server.cache-from=type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ github.event.pull_request.head.sha || github.sha }}
            model-server.cache-from=type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }}
            model-server.cache-from=type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache
-            model-server.cache-from=type=registry,ref=onyxdotapp/onyx-model-server:latest
+            model-server.cache-from=type=registry,ref=${{ env.BASE_IMAGE_REGISTRY }}/onyxdotapp/onyx-model-server:latest
            model-server.cache-to=type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ github.event.pull_request.head.sha || github.sha }},mode=max
            model-server.cache-to=type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache-${{ steps.format-branch.outputs.cache-suffix }},mode=max
            model-server.cache-to=type=registry,ref=${{ env.RUNS_ON_ECR_CACHE }}:model-server-cache,mode=max
@@ -76,19 +76,6 @@ jobs:
        with:
          persist-credentials: false

-      - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@ec61189d14ec14c8efccab744f656cffd0e33f37
-        with:
-          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
-          aws-region: us-east-2
-
-      - name: Get AWS Secrets
-        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
-        with:
-          secret-ids: |
-            DOCKER_USERNAME, test/docker-username
-            DOCKER_TOKEN, test/docker-token
-
      - name: Build backend image
        uses: ./.github/actions/build-backend-image
        with:
@@ -97,8 +84,7 @@ jobs:
          pr-number: ${{ github.event.pull_request.number }}
          github-sha: ${{ github.sha }}
          run-id: ${{ github.run_id }}
-          docker-username: ${{ env.DOCKER_USERNAME }}
-          docker-token: ${{ env.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}
          docker-no-cache: ${{ vars.DOCKER_NO_CACHE == 'true' && 'true' || 'false' }}

  build-model-server-image:
@@ -119,19 +105,6 @@ jobs:
        with:
          persist-credentials: false

-      - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@ec61189d14ec14c8efccab744f656cffd0e33f37
-        with:
-          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
-          aws-region: us-east-2
-
-      - name: Get AWS Secrets
-        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
-        with:
-          secret-ids: |
-            DOCKER_USERNAME, test/docker-username
-            DOCKER_TOKEN, test/docker-token
-
      - name: Build model server image
        uses: ./.github/actions/build-model-server-image
        with:
@@ -140,8 +113,7 @@ jobs:
          pr-number: ${{ github.event.pull_request.number }}
          github-sha: ${{ github.sha }}
          run-id: ${{ github.run_id }}
-          docker-username: ${{ env.DOCKER_USERNAME }}
-          docker-token: ${{ env.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

  build-devcontainer-image:
    runs-on:
@@ -161,19 +133,6 @@ jobs:
        with:
          persist-credentials: false

-      - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@ec61189d14ec14c8efccab744f656cffd0e33f37
-        with:
-          role-to-assume: ${{ secrets.AWS_OIDC_ROLE_ARN }}
-          aws-region: us-east-2
-
-      - name: Get AWS Secrets
-        uses: aws-actions/aws-secretsmanager-get-secrets@a9a7eb4e2f2871d30dc5b892576fde60a2ecc802
-        with:
-          secret-ids: |
-            DOCKER_USERNAME, test/docker-username
-            DOCKER_TOKEN, test/docker-token
-
      - name: Build devcontainer image
        uses: ./.github/actions/build-devcontainer-image
        with:
@@ -182,8 +141,7 @@ jobs:
          pr-number: ${{ github.event.pull_request.number }}
          github-sha: ${{ github.sha }}
          run-id: ${{ github.run_id }}
-          docker-username: ${{ env.DOCKER_USERNAME }}
-          docker-token: ${{ env.DOCKER_TOKEN }}
+          ecr-registry: ${{ vars.ECR_REGISTRY }}

  provider-chat-test:
    needs:
@@ -5,7 +5,11 @@
 # site-packages + console scripts are copied into the runtime stage; the build toolchain never
 # reaches the shipped image.
 ####################################################################################################
-FROM python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2 AS builder
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits. Declared before the first FROM so it applies to every base image below.
+ARG BASE_IMAGE_REGISTRY=docker.io
+FROM ${BASE_IMAGE_REGISTRY}/library/python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2 AS builder

 COPY --from=ghcr.io/astral-sh/uv:0.9.9 /uv /uvx /bin/

@@ -53,7 +57,7 @@ RUN uv pip install --system --no-cache-dir --no-deps --require-hashes \
 # The actual shipped image. Installs only runtime system libraries and copies the already-built
 # Python packages from the builder stage.
 ####################################################################################################
-FROM python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2 AS runtime
+FROM ${BASE_IMAGE_REGISTRY}/library/python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2 AS runtime

 LABEL com.danswer.maintainer="founders@onyx.app"
 LABEL com.danswer.description="This image is the web/frontend container of Onyx which \
@@ -1,5 +1,10 @@
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits.
+ARG BASE_IMAGE_REGISTRY=docker.io
+
 # Base stage with dependencies
-FROM python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2 AS base
+FROM ${BASE_IMAGE_REGISTRY}/library/python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2 AS base

 ENV ONYX_RUNNING_IN_DOCKER="true" \
    HF_HOME=/app/.cache/huggingface
@@ -3,7 +3,17 @@
 # User-shared sandbox: one pod per user, sessions created via kubectl exec.
 # See docs/craft/sandbox/image-and-spinup.md for image-layer rationale.

-FROM node:20-slim@sha256:2cf067cfed83d5ea958367df9f966191a942351a2df77d6f0193e162b5febfc0
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits.
+ARG BASE_IMAGE_REGISTRY=docker.io
+
+# bun + s5cmd binary sources. Pinned via the registry prefix in their own stages because buildx
+# rejects variable expansion directly in `COPY --from=` -- the ARG is only expandable in a FROM.
+FROM ${BASE_IMAGE_REGISTRY}/oven/bun:1.3.14@sha256:e10577f0db68676a7024391c6e5cb4b879ebd17188ab750cf10024a6d700e5c4 AS bun_source
+FROM ${BASE_IMAGE_REGISTRY}/peakcom/s5cmd:v2.3.0@sha256:2ff939e2ee3c76adcadd78dbfc3e2569b18a3743ed9dcfccb1ec589af7fb9903 AS s5cmd_source
+
+FROM ${BASE_IMAGE_REGISTRY}/library/node:20-slim@sha256:2cf067cfed83d5ea958367df9f966191a942351a2df77d6f0193e162b5febfc0

 # Set ENABLE_SKILLS=false in dev/CI to skip skill-runtime deps (LibreOffice,
 # poppler, fonts, pptxgenjs) and shave ~700 MB. Skills themselves are pushed
@@ -81,11 +91,9 @@ RUN if [ "$ENABLE_SKILLS" = "true" ]; then \
    rm -rf /root/.npm; \
    fi

-COPY --from=oven/bun:1.3.14@sha256:e10577f0db68676a7024391c6e5cb4b879ebd17188ab750cf10024a6d700e5c4 \
-    /usr/local/bin/bun /usr/local/bin/bun
-
-COPY --from=peakcom/s5cmd:v2.3.0@sha256:2ff939e2ee3c76adcadd78dbfc3e2569b18a3743ed9dcfccb1ec589af7fb9903 \
-    /s5cmd /usr/local/bin/s5cmd
+# bun + s5cmd copied from the binary-source stages defined at the top of this file.
+COPY --from=bun_source /usr/local/bin/bun /usr/local/bin/bun
+COPY --from=s5cmd_source /s5cmd /usr/local/bin/s5cmd

 USER sandbox
 RUN curl -fsSL https://opencode.ai/install \
@@ -1,4 +1,8 @@
-FROM python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits.
+ARG BASE_IMAGE_REGISTRY=docker.io
+FROM ${BASE_IMAGE_REGISTRY}/library/python:3.11-slim@sha256:6d85378d88a19cd4d76079817532d62232be95757cb45945a99fec8e8084b9c2

 WORKDIR /app

@@ -1,4 +1,8 @@
-FROM golang:1.26-alpine@sha256:2389ebfa5b7f43eeafbd6be0c3700cc46690ef842ad962f6c5bd6be49ed82039 AS builder
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits.
+ARG BASE_IMAGE_REGISTRY=docker.io
+FROM ${BASE_IMAGE_REGISTRY}/library/golang:1.26-alpine@sha256:2389ebfa5b7f43eeafbd6be0c3700cc46690ef842ad962f6c5bd6be49ed82039 AS builder

 WORKDIR /app
 COPY ./ .
@@ -411,7 +411,7 @@ services:
        max-file: "6"

  relational_db:
-    image: postgres:15.2-alpine
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/library/postgres:15.2-alpine
    shm_size: 1g
    command: -c 'max_connections=250'
    restart: unless-stopped
@@ -426,7 +426,7 @@ services:
      - db_volume:/var/lib/postgresql/data

  opensearch:
-    image: opensearchproject/opensearch:3.6.0
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/opensearchproject/opensearch:3.6.0
    restart: unless-stopped
    # OpenSearch is the search backend and is enabled by default. To run against
    # an external OpenSearch instance, set OPENSEARCH_HOST in your env and
@@ -465,7 +465,7 @@ services:
        max-file: "6"

  nginx:
-    image: nginx:1.25.5-alpine
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/library/nginx:1.25.5-alpine
    restart: unless-stopped
    # nginx will immediately crash with `nginx: [emerg] host not found in upstream`
    # if api_server / web_server are not up
@@ -492,7 +492,7 @@ services:
      && /tmp/run-nginx.sh app.conf.template"

  minio:
-    image: minio/minio:RELEASE.2025-07-23T15-54-02Z-cpuv1
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/minio/minio:RELEASE.2025-07-23T15-54-02Z-cpuv1
    restart: unless-stopped
    ports:
      - "9004:9000"
@@ -511,7 +511,7 @@ services:
      retries: 3

  cache:
-    image: redis:7.4-alpine
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/library/redis:7.4-alpine
    restart: unless-stopped
    ports:
      - "6379:6379"
@@ -377,7 +377,7 @@ services:
      start_period: 600s

  relational_db:
-    image: postgres:15.2-alpine
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/library/postgres:15.2-alpine
    shm_size: 1g
    command: -c 'max_connections=250'
    env_file:
@@ -402,7 +402,7 @@ services:
      - db_volume:/var/lib/postgresql/data

  opensearch:
-    image: opensearchproject/opensearch:3.6.0
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/opensearchproject/opensearch:3.6.0
    restart: unless-stopped
    # OpenSearch is the search backend and is enabled by default. To run against
    # an external OpenSearch instance, set OPENSEARCH_HOST in your env and
@@ -441,7 +441,7 @@ services:
        max-file: "6"

  nginx:
-    image: nginx:1.25.5-alpine
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/library/nginx:1.25.5-alpine
    restart: unless-stopped
    # nginx will immediately crash with `nginx: [emerg] host not found in upstream`
    # if api_server / web_server are not up
@@ -501,7 +501,7 @@ services:
      start_period: 30s

  cache:
-    image: redis:7.4-alpine
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/library/redis:7.4-alpine
    restart: unless-stopped
    # DEV: To expose ports, either:
    # 1. Use docker-compose.dev.yml: docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --wait
@@ -519,7 +519,7 @@ services:
      - /data

  minio:
-    image: minio/minio:RELEASE.2025-07-23T15-54-02Z-cpuv1
+    image: ${BASE_IMAGE_REGISTRY:-docker.io}/minio/minio:RELEASE.2025-07-23T15-54-02Z-cpuv1
    profiles: ["s3-filestore"]
    restart: unless-stopped
    # DEV: To expose ports, either:
@@ -26,6 +26,13 @@ variable "TAG" {
  default = "latest"
 }

+# Registry prefix for base images (the Dockerfiles' BASE_IMAGE_REGISTRY ARG). Defaults to
+# Docker Hub; CI overrides this (via the matching environment variable, which bake reads
+# automatically) to the ECR pull-through cache so base-image pulls avoid Docker Hub rate limits.
+variable "BASE_IMAGE_REGISTRY" {
+  default = "docker.io"
+}
+
 target "backend" {
  context    = "backend"
  dockerfile = "Dockerfile"
@@ -36,6 +43,10 @@ target "backend" {
  ]
  cache-to   = ["type=inline"]

+  args = {
+    BASE_IMAGE_REGISTRY = "${BASE_IMAGE_REGISTRY}"
+  }
+
  tags      = ["${BACKEND_REPOSITORY}:${TAG}"]
 }

@@ -49,6 +60,10 @@ target "web" {
  ]
  cache-to   = ["type=inline"]

+  args = {
+    BASE_IMAGE_REGISTRY = "${BASE_IMAGE_REGISTRY}"
+  }
+
  tags      = ["${WEB_SERVER_REPOSITORY}:${TAG}"]
 }

@@ -63,6 +78,10 @@ target "model-server" {
  ]
  cache-to   = ["type=inline"]

+  args = {
+    BASE_IMAGE_REGISTRY = "${BASE_IMAGE_REGISTRY}"
+  }
+
  tags      = ["${MODEL_SERVER_REPOSITORY}:${TAG}"]
 }

@@ -76,6 +95,10 @@ target "cli" {
  ]
  cache-to   = ["type=inline"]

+  args = {
+    BASE_IMAGE_REGISTRY = "${BASE_IMAGE_REGISTRY}"
+  }
+
  tags      = ["${CLI_REPOSITORY}:${TAG}"]
 }

@@ -89,5 +112,9 @@ target "devcontainer" {
  ]
  cache-to   = ["type=inline"]

+  args = {
+    BASE_IMAGE_REGISTRY = "${BASE_IMAGE_REGISTRY}"
+  }
+
  tags      = ["${DEVCONTAINER_REPOSITORY}:${TAG}"]
 }
@@ -1,4 +1,8 @@
-FROM node:24-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f AS base
+# Registry prefix for base images. Defaults to Docker Hub; CI overrides this to the ECR
+# pull-through cache (<account>.dkr.ecr.us-east-2.amazonaws.com/docker-hub) to avoid Docker
+# Hub rate limits.
+ARG BASE_IMAGE_REGISTRY=docker.io
+FROM ${BASE_IMAGE_REGISTRY}/library/node:24-alpine@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f AS base

 LABEL com.onyx.maintainer="founders@onyx.app"
 LABEL com.onyx.description="This image is the web/frontend container of Onyx which \
@@ -7,12 +11,16 @@ have a contract or agreement with DanswerAI, you are not permitted to use the En
 Edition features outside of personal development or testing purposes. Please reach out to \
 founders@onyx.app for more information. Please visit https://github.com/onyx-dot-app/onyx"

+# bun binary source. Pinned via the registry prefix in its own stage because buildx
+# rejects variable expansion directly in `COPY --from=` -- the ARG is only expandable in a FROM.
+FROM ${BASE_IMAGE_REGISTRY}/oven/bun:1-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0 AS bun_source
+
 # Step 1. Install dependencies + rebuild the source code only when needed
 FROM base AS builder
 # Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
 RUN apk add --no-cache libc6-compat
-COPY --from=oven/bun:1-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0 /usr/local/bin/bun /usr/local/bin/bun
-COPY --from=oven/bun:1-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0 /usr/local/bin/bunx /usr/local/bin/bunx
+COPY --from=bun_source /usr/local/bin/bun /usr/local/bin/bun
+COPY --from=bun_source /usr/local/bin/bunx /usr/local/bin/bunx
 WORKDIR /app

 # Copy package files + the full opal workspace source so that opal's `prepare`