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 ccf3c9a101
commit ba3aa7443f
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 ## 3. Container Registries, Mirrors & Image Distribution
Our infrastructure uses a tiered registry architecture to balance local caching, Our infrastructure uses a tiered registry architecture to clearly separate
private custom image hosting, and universal build portability: custom application images from upstream cached dependencies:
### 3.1 Registry Tier Classification ### 3.1 Registry Tier Classification
1. **Primary Custom Image Registry (`${REG}` $\rightarrow$ `quay.atyg.org`):** 1. **Primary Custom Image Registry (`${REG}` $\rightarrow$ `quay.atyg.org`):**
- Hosts all internally built, project-specific custom images - Hosts all internally built, project-specific custom application images
(`${REG}/library/<image>:<tag>`). (`${REG}/library/<app>:<tag>`).
- Examples: `${REG}/library/auth-yes-api:latest`, - Example: `${REG}/library/auth-yes-api:latest` (built from project source).
`${REG}/library/spire-server:latest`, `${REG}/library/spire-agent:latest`. - Retained **indefinitely** on disk (auto-pruning disabled).
- Retention policy is set for **indefinite storage** (auto-pruning disabled).
2. **Docker Hub Pull-Through Cache (`acr.atyg.org`):** 2. **Docker Hub Pull-Through Cache (`acr.atyg.org`):**
- Proxies and indefinitely caches upstream Docker Hub images on the local - Proxies and indefinitely caches upstream Docker Hub infrastructure images
network. on the local network.
- Examples: `acr.atyg.org/library/postgres:18-alpine`, - Examples: `acr.atyg.org/library/postgres:18-alpine`,
`acr.atyg.org/valkey/valkey:8-alpine`, `acr.atyg.org/library/alpine:3.20`. `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`):** 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`, - Examples: `${GHCR_REG}/spiffe/spire-server:1.9.3`,
`${GHCR_REG}/spiffe/spire-agent:1.9.3`. `${GHCR_REG}/spiffe/spire-agent:1.9.3`.
### 3.2 Universal Dockerfile Portability (Jules & External CI) ### 3.2 Universal Dockerfile Portability (Jules & External CI)
- **Public Upstream Defaults:** Dockerfiles must declare public upstream - **Public Upstream Defaults:** Dockerfiles for custom application images or
registries by default so external agents (like Jules) and cloud CI runners can wrappers must declare public upstream registries by default so external agents
build without private `.atyg.org` DNS: (like Jules) and cloud CI runners can build without private `.atyg.org` DNS:
```dockerfile ```dockerfile
ARG SPIRE_UPSTREAM=ghcr.io/spiffe/spire-server:1.9.3
ARG BASE_IMAGE=alpine:3.20 ARG BASE_IMAGE=alpine:3.20
FROM ${SPIRE_UPSTREAM} AS upstream
FROM ${BASE_IMAGE} FROM ${BASE_IMAGE}
``` ```
- **Local Build Acceleration:** Local builds and CLI scripts (`infra/setup.ts`) - **Local Build Acceleration:** Local builds and CLI scripts (`infra/setup.ts`)
can optionally pass `--build-arg` to pull through local mirrors can optionally pass `--build-arg` to pull through local mirrors
(`ghcr.atyg.org`, `acr.atyg.org`). (`ghcr.atyg.org`, `acr.atyg.org`).
- **Push Destination:** Custom built images are tagged and pushed to the local - **Push Destination:** Custom built application images are tagged and pushed to
authority `${REG}/library/...` (`quay.atyg.org`). the local authority `${REG}/library/...` (`quay.atyg.org`).
### 3.3 Compose Variable Cleanliness ### 3.3 Compose Variable Cleanliness
- **No Inline Defaults:** Always write clean variable references in Compose - **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`). `image: ${GHCR_REG}/spiffe/spire-server:1.9.3`).
- **Centralized Values:** Default registry variables belong strictly in `.env` - **Centralized Values:** Default registry variables belong strictly in `.env`
and `infra/setup.ts`. and `infra/setup.ts`.