tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify custom project images vs upstream open-source infrastructure in COMPOSE_CONVENTIONS.md

Browse Source
This commit is contained in:
Tyler Gillispie 2026-08-23 10:23:37 -07:00
parent 036a735ee0
commit 29bc8e1a58
1 changed files with 16 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
COMPOSE_CONVENTIONS.md
View File

@ -60,49 +60,46 @@ across our infrastructure.
## 3. Container Registries, Mirrors & Image Distribution
Our infrastructure uses a tiered registry architecture to balance local caching,
private custom image hosting, and universal build portability:
Our infrastructure uses a tiered registry architecture to clearly separate
custom application images from upstream cached dependencies:
### 3.1 Registry Tier Classification
1. **Primary Custom Image Registry (`${REG}` $\rightarrow$ `quay.atyg.org`):**
- Hosts all internally built, project-specific custom images
(`${REG}/library/<image>:<tag>`).
- Examples: `${REG}/library/auth-yes-api:latest`,
`${REG}/library/spire-server:latest`, `${REG}/library/spire-agent:latest`.
- Retention policy is set for **indefinite storage** (auto-pruning disabled).
- Hosts all internally built, project-specific custom application images
(`${REG}/library/<app>:<tag>`).
- Example: `${REG}/library/auth-yes-api:latest` (built from project source).
- Retained **indefinitely** on disk (auto-pruning disabled).
2. **Docker Hub Pull-Through Cache (`acr.atyg.org`):**
- Proxies and indefinitely caches upstream Docker Hub images on the local
network.
- Proxies and indefinitely caches upstream Docker Hub infrastructure 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.
- Proxies and caches upstream GitHub Container Registry infrastructure
images.
- 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:
- **Public Upstream Defaults:** Dockerfiles for custom application images or
wrappers 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`).
- **Push Destination:** Custom built application 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`,
files (`image: ${REG}/library/auth-yes-api:latest`,
`image: ${GHCR_REG}/spiffe/spire-server:1.9.3`).
- **Centralized Values:** Default registry variables belong strictly in `.env`
and `infra/setup.ts`.