@@ -93,6 +93,28 @@ These auto-cloned repos are tracked and **removed automatically on exit**
 (via an EXIT trap), so `src/` directories stay clean in the repo (only a
 `.gitkeep` is committed).
 
+Git source caching is optional and is separate from the package caches
+described below. Enable it for local source operations with:
+
+```bash
+SOURCE_CACHE=true STREAM=master tox -ebuild -- nova
+```
+
+When enabled, repository objects are retained as bare repositories under
+`.tmp/source_cache/<host>/<organization>/<repository>.git`. Branch and tag refs
+are refreshed once per repository in each `build.sh` invocation, then a fast
+local clone is materialized at the exact pinned commit. The disposable clone is
+removed on exit while the bare cache remains for later invocations. Set
+`SOURCE_CACHE_DIR` to override the cache location. Source caching defaults to
+`false`; direct temporary clones retain the previous behavior when disabled.
+
+To discard all cached Git objects and make the next cached source operation
+fetch them again, remove the cache directory:
+
+```bash
+rm -rf .tmp/source_cache
+```
+
 If a checkout already exists in `src/` (e.g., a local development clone),
 `build.sh` uses it as-is and does **not** remove it on exit. This lets you
 work on a local branch without `build.sh` overwriting it.
@@ -288,6 +310,67 @@ STREAM=stable tox -ecustom -- build watcher/watcher-base
 tox -ecustom -- list
 ```
 
+### Optional local package caches
+
+A developer-only Compose stack under `tools/local-package-cache/` provides
+[Proxpi](https://github.com/EpicWink/proxpi) for Python downloads and
+Squid for plain-HTTP RPM repository traffic. Package caching is disabled
+by default and affects only local `build` and `build-parallel` actions when
+`LOCAL_PACKAGE_CACHE=true`. Normal builds and Konflux builds remain unchanged.
+The cache-service lifecycle is intentionally separate from `build.sh`.
+
+`podman compose` requires a Compose provider. On CentOS Stream, install and
+verify `podman-compose` with:
+
+```bash
+sudo dnf install podman-compose
+podman compose version
+```
+
+Start the services, verify them, and opt a build into package caching:
+
+```bash
+LOCAL_CACHE_BIND_ADDRESS=0.0.0.0 \
+  podman compose -f tools/local-package-cache/compose.yaml up -d
+podman compose -f tools/local-package-cache/compose.yaml ps
+LOCAL_PACKAGE_CACHE=true STREAM=master tox -ebuild -- glance
+```
+
+Compose creates and manages the named Proxpi and Squid volumes declared
+in `compose.yaml`; do not create those volumes manually. They persist downloaded
+content across container replacement and ordinary `down`/`up` cycles.
+
+Build containers reach the published ports through
+`host.containers.internal`. Rootless containers generally cannot reach services
+bound only to host loopback, so the example publishes on all host interfaces.
+Binding to `0.0.0.0` can expose unauthenticated cache services to the local
+network; use host firewall rules or set `LOCAL_CACHE_BIND_ADDRESS` to a more
+specific reachable host address when possible. The Compose file defaults to
+`127.0.0.1` for safety when no address is specified.
+
+The build fails before invoking Buildah when `LOCAL_PACKAGE_CACHE=true` and
+either service is unavailable. Endpoint overrides are available through
+`LOCAL_PYPI_INDEX_URL`, `LOCAL_PYPI_TRUSTED_HOST`, `LOCAL_RPM_PROXY`,
+`LOCAL_PYPI_HEALTH_URL`, and `LOCAL_RPM_HEALTH_URL`.
+
+Stop the services while retaining downloaded packages:
+
+```bash
+podman compose -f tools/local-package-cache/compose.yaml down
+```
+
+Delete the services and their package-cache volumes for a cold package fetch:
+
+```bash
+podman compose -f tools/local-package-cache/compose.yaml down -v
+```
+
+This proof of concept caches external downloads only. It does not cache wheels
+built from the OpenStack source checkouts. HTTPS repositories normally pass
+through without TLS interception. Squid fetches the HTTPS origin behind
+`mirror.stream.centos.org` itself so the existing HTTP repository URLs remain
+cacheable.
+
 ### Initial setup
 
 1. Create `containers/<project>/sources.txt` with entries for each stream. Add
@@ -437,6 +520,37 @@ validation, builds, publication, result generation, and cleanup target that
 host explicitly. The Zuul executor controls Ansible but does not perform those
 mutations.
 
+The provider copies the RDO base job's `/etc/pip.conf` into a job-local file
+and mounts it into Buildah so Python downloads use the provider mirror. It also
+can run an ephemeral Squid container directly with Podman. Squid caches direct
+upstream HTTP traffic or can sit in front of the provider's CentOS mirror. The
+cache is published on the disposable builder and Buildah RUN steps reach it through
+`host.containers.internal`. Proxy values are passed as build arguments so
+host-side base-image pulls are not routed through the package cache. The cache
+intentionally listens without authentication on all interfaces of the
+disposable CI builder. Plain-HTTP CentOS Stream requests can be remapped to the
+provider's CentOS mirror. Otherwise, Squid rewrites plain-HTTP CentOS requests
+to the upstream HTTPS origin before fetching them, without intercepting client
+TLS. The job does not consume host RPM repository files or require
+`podman-compose`. Post-run cleanup
+removes the cache container, its volumes, and generated configuration.
+Persistent source caching is explicitly disabled
+because Zuul already stages speculative source trees and the builder is
+disposable.
+
+`s2i_ci_use_provider_pip_mirror` controls whether the parent-provided
+`pip.conf` is mounted, `s2i_ci_enable_rpm_cache` controls the RPM proxy, and
+`s2i_ci_rpm_cache_use_provider_mirror` controls its optional CentOS Stream
+backend remap. Disabling Squid leaves RPM repository access unchanged;
+the provider mirror still applies to Python downloads when its pip option is
+enabled. The content-provider currently disables the RPM backend remap because
+the Vexxhost mirror does not carry the CentOS Stream 10 SIG repositories used
+by these images. Squid therefore caches their original repository URLs.
+Collapsed forwarding combines concurrent requests for the same object, and
+`repomd.xml` remains fresh for the two-hour job despite DNF cache-bypass
+headers. Squid access and error logs are staged under
+`zuul-output/logs/squid/` for troubleshooting.
+
 In this repository the provider defaults to `all`, so every maintained image
 is built from its exact `sources.txt` pins. A child job can set `s2i_ci_images`
 to an explicit list of image targets; the provider resolves the selection
 
@@ -7,6 +7,25 @@
     s2i_ci_registry_connection_file: >-
       {{ s2i_ci_output_dir }}/.s2i-ci-registry-connection.json
     s2i_ci_workspace_root: "{{ zuul_user_dir | default(ansible_user_dir) }}"
+    s2i_ci_package_cache_dir: >-
+      {{ ansible_user_dir }}/.cache/s2i-ci-package-cache
+    s2i_ci_pip_config_file: "{{ s2i_ci_package_cache_dir }}/pip.conf"
+    s2i_ci_package_proxy: http://host.containers.internal:3142
+    s2i_ci_mirror_fqdn: >-
+      mirror.{{ nodepool.region | lower }}.{{ nodepool.cloud | lower }}.rdoproject.org
+    s2i_ci_build_no_proxy: >-
+      {{
+        (
+          ['localhost', '127.0.0.1', 'host.containers.internal',
+           s2i_ci_registry.public_host]
+          + ([s2i_ci_mirror_fqdn]
+             if ((s2i_ci_use_provider_pip_mirror | default(true) | bool) or
+                 ((s2i_ci_enable_rpm_cache | default(true) | bool) and
+                  (s2i_ci_rpm_cache_use_provider_mirror |
+                   default(true) | bool)))
+             else [])
+        ) | join(',')
+      }}
 
   tasks:
     - name: Default optional selective provider inputs
@@ -210,6 +229,7 @@
           environment:
             STREAM: "{{ s2i_ci_stream }}"
             REQUIREMENTS_SRC: "{{ s2i_ci_requirements_src | default('') }}"
+            SOURCE_CACHE: "false"
           register: s2i_ci_sync_locks
           changed_when: true
       always:
@@ -222,20 +242,43 @@
               {{ s2i_ci_sync_locks.stdout | default('') }}
               {{ s2i_ci_sync_locks.stderr | default('') }}
 
+    - name: Prepare the build command environment
+      ansible.builtin.set_fact:
+        s2i_ci_build_environment: >-
+          {{
+            {
+              'STREAM': s2i_ci_stream,
+              'REGISTRY': s2i_ci_registry.endpoint,
+              'NAMESPACE': s2i_ci_namespace,
+              'TAG': s2i_ci_tag,
+              'PARALLEL': s2i_ci_parallel | string,
+              'BUILD_LOGS_DIR': s2i_ci_log_dir,
+              'SOURCE_CACHE': 'false'
+            }
+            | combine(
+                {'BUILD_PIP_CONFIG_FILE': s2i_ci_pip_config_file}
+                if s2i_ci_use_provider_pip_mirror | default(true) | bool
+                else {}
+              )
+            | combine(
+                {
+                  'BUILD_HTTP_PROXY': s2i_ci_package_proxy,
+                  'BUILD_HTTPS_PROXY': s2i_ci_package_proxy,
+                  'BUILD_NO_PROXY': s2i_ci_build_no_proxy
+                }
+                if s2i_ci_enable_rpm_cache | default(true) | bool
+                else {}
+              )
+          }}
+
     - name: Build selected images
       ansible.builtin.command:
         argv:
           - "{{ s2i_ci_container_repo }}/build.sh"
           - build-parallel
           - "{{ s2i_ci_target_expression }}"
         chdir: "{{ s2i_ci_container_repo }}"
-      environment:
-        STREAM: "{{ s2i_ci_stream }}"
-        REGISTRY: "{{ s2i_ci_registry.endpoint }}"
-        NAMESPACE: "{{ s2i_ci_namespace }}"
-        TAG: "{{ s2i_ci_tag }}"
-        PARALLEL: "{{ s2i_ci_parallel | string }}"
-        BUILD_LOGS_DIR: "{{ s2i_ci_log_dir }}"
+      environment: "{{ s2i_ci_build_environment }}"
       register: s2i_ci_build
       changed_when: s2i_ci_build.rc == 0
 
 
@@ -5,6 +5,8 @@
   vars:
     s2i_ci_output_dir: "{{ ansible_user_dir }}/zuul-output"
     s2i_ci_log_dir: "{{ s2i_ci_output_dir }}/logs/container-build"
+    s2i_ci_squid_log_dir: >-
+      {{ ansible_user_dir }}/.cache/s2i-ci-package-cache/squid
 
   tasks:
     - name: Ensure the container build log directory exists
@@ -14,6 +16,21 @@
         mode: "0755"
       failed_when: false
 
+    - name: Stage Squid file logs
+      when: s2i_ci_enable_rpm_cache | default(true) | bool
+      block:
+        - name: Run the trusted output staging role
+          ansible.builtin.include_role:
+            name: stage-output
+          vars:
+            stage_dir: "{{ s2i_ci_output_dir }}"
+            zuul_copy_output:
+              "{{ s2i_ci_squid_log_dir }}": logs
+      rescue:
+        - name: Report non-fatal Squid log staging failure
+          ansible.builtin.debug:
+            msg: Squid file log staging failed; cleanup will continue
+
     - name: Collect registry and build container logs
       block:
         - name: Run the trusted container log collection role
@@ -24,7 +41,7 @@
       rescue:
         - name: Report non-fatal Zuul container log collection failure
           ansible.builtin.debug:
-            msg: Container log collection failed; registry cleanup will continue
+            msg: Container log collection failed; cache cleanup will continue
 
 - name: Remove exact workflow images
   ansible.builtin.import_playbook: ../shared/cleanup-images.yaml
@@ -45,6 +62,20 @@
       changed_when: s2i_ci_removed_registry.stdout | length > 0
       failed_when: false
 
+    - name: Remove the RPM package-cache container and anonymous volumes
+      ansible.builtin.command:
+        argv: [podman, rm, --force, --volumes, s2i_squid]
+      register: s2i_ci_removed_package_cache
+      changed_when: s2i_ci_removed_package_cache.rc == 0
+      failed_when: false
+
+    - name: Remove the job-local package-cache configuration
+      become: true
+      ansible.builtin.file:
+        path: "{{ ansible_user_dir }}/.cache/s2i-ci-package-cache"
+        state: absent
+      failed_when: false
+
     - name: Remove persisted registry connection data
       ansible.builtin.file:
         path: "{{ s2i_ci_registry_connection_file }}"
 
@@ -2,6 +2,9 @@
 - name: Prepare shared build tools
   ansible.builtin.import_playbook: ../shared/prepare-host.yaml
 
+- name: Prepare package caches for container builds
+  ansible.builtin.import_playbook: prepare-mirrors.yaml
+
 - name: Deploy a plain Docker registry on the builder
   hosts: builder
   vars: