docs: clarify registry tier classification, mirrors, and Dockerfile portability in COMPOSE_CONVENTIONS.md

COMPOSE_CONVENTIONS.md

@@ -58,18 +58,54 @@ across our infrastructure.
 
 ---
 
-## 3. Environment Variables & Clean YAML
+## 3. Container Registries, Mirrors & Image Distribution
 
-- **No Inline Variable Fallbacks in Compose:**
+Our infrastructure uses a tiered registry architecture to balance local caching,
-  - Always write clean variable references: `${REG}`, `${GHCR_REG}`,
+private custom image hosting, and universal build portability:
-    `${SYSTEM_DOMAIN}`, `${SPIRE_DATA_PATH}`.
+
-  - Do NOT use inline defaults (e.g., `${REG:-quay.atyg.org}`) inside the
+### 3.1 Registry Tier Classification
-    Compose file.
+
-  - All default values belong strictly in `.env` or the interactive setup wizard
+1. **Primary Custom Image Registry (`${REG}` $\rightarrow$ `quay.atyg.org`):**
-    (`infra/setup.ts`).
+   - Hosts all internally built, project-specific custom images
-- **Parameterize Registry Endpoints:**
+     (`${REG}/library/<image>:<tag>`).
-  - Always prefix images with `${REG}/library/<image>:<tag>` or
+   - Examples: `${REG}/library/auth-yes-api:latest`,
-    `${GHCR_REG}/<org>/<image>:<tag>`.
+     `${REG}/library/spire-server:latest`, `${REG}/library/spire-agent:latest`.
+   - Retention policy is set for **indefinite storage** (auto-pruning disabled).
+2. **Docker Hub Pull-Through Cache (`acr.atyg.org`):**
+   - Proxies and indefinitely caches upstream Docker Hub images on the local
+     network.
+   - Examples: `acr.atyg.org/library/postgres:18-alpine`,
+     `acr.atyg.org/valkey/valkey:8-alpine`, `acr.atyg.org/library/alpine:3.20`.
+3. **GHCR Pull-Through Mirror (`${GHCR_REG}` $\rightarrow$ `ghcr.atyg.org`):**
+   - Proxies and caches GitHub Container Registry packages.
+   - Examples: `${GHCR_REG}/spiffe/spire-server:1.9.3`,
+     `${GHCR_REG}/spiffe/spire-agent:1.9.3`.
+
+### 3.2 Universal Dockerfile Portability (Jules & External CI)
+
+- **Public Upstream Defaults:** Dockerfiles must declare public upstream
+  registries by default so external agents (like Jules) and cloud CI runners can
+  build without private `.atyg.org` DNS:
+  ```dockerfile
+  ARG SPIRE_UPSTREAM=ghcr.io/spiffe/spire-server:1.9.3
+  ARG BASE_IMAGE=alpine:3.20
+
+  FROM ${SPIRE_UPSTREAM} AS upstream
+  FROM ${BASE_IMAGE}
+  ```
+- **Local Build Acceleration:** Local builds and CLI scripts (`infra/setup.ts`)
+  can optionally pass `--build-arg` to pull through local mirrors
+  (`ghcr.atyg.org`, `acr.atyg.org`).
+- **Push Destination:** Custom built images are tagged and pushed to the local
+  authority `${REG}/library/...` (`quay.atyg.org`).
+
+### 3.3 Compose Variable Cleanliness
+
+- **No Inline Defaults:** Always write clean variable references in Compose
+  files (`image: ${REG}/library/spire-server:latest`,
+  `image: ${GHCR_REG}/spiffe/spire-server:1.9.3`).
+- **Centralized Values:** Default registry variables belong strictly in `.env`
+  and `infra/setup.ts`.
 
 ---