Image Tagging Strategy
Image Tagging Strategy
Cbox PHP Base Images follow a clear, predictable tagging strategy with four image tiers and rootless variants.
Tag Format
{image-type}:{php-version}-{os}[-tier][-rootless][-vN]
Release Channels & Pinning
A tag can promise one of two things — identical bits (reproducibility) or a stable behavior contract (no breaking changes) — and no single tag can stay CVE-free while promising identical bits. So we publish three kinds of tags:
| Kind | Example | Security updates? | Crosses tooling majors? | Use when |
|---|---|---|---|---|
| Rolling | 8.5-trixie |
✅ yes | ✅ yes (follows latest release) | You track upstream and want everything newest |
| Channel | 8.5-trixie-v2 |
✅ yes | ❌ never | Recommended for production: entrypoint/tooling behavior locked to major v2, OS security patches keep flowing |
| Digest / SHA | 8.5-trixie-sha-abc1234 or @sha256:… |
❌ immutable | — | Audits, reproductions, byte-exact rollbacks. Ages by design — contains the CVEs of its build day |
GitHub releases (vX.Y.Z) version the image tooling — entrypoint behavior,
cbox-init version, nginx modules, the extension set — not PHP itself. The
channel tag -vN follows the newest release within major N.
Support policy: the current major is checked hourly, with apt-only
patching at a six-hour cadence and a 30-day full-build limit. When a
new major ships, the previous major's channel keeps receiving weekly security
rebuilds for 6 months (from a release/vN maintenance branch), then goes
EOL. Which majors are in support is recorded in versions.json under
release.supported_majors.
How v1 is kept patched: scheduled workflows only run on the default
branch, so maintain-previous-majors.yml on main starts the release/v1
build chain every Monday, and the branch chains its own downstream images.
v1 (Debian 12 Bookworm) is maintained until 2027-05-07, as recorded in
versions.json under release.maintenance.
Known exploited vulnerabilities: the hourly watch scans the current and
every maintained channel against CISA's
KEV catalog at
every severity, fixed or not. A fixable KEV entry blocks tag promotion and
triggers a rebuild. An unfixed one fails the watch until Debian ships a fix,
unless security/kev-exceptions.json records why the image is not exposed,
with an expiry date.
# Recommended production pin: behavior locked, security patches current
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-v2
Image Tiers
| Tier | Tag Suffix | Size | Use Case |
|---|---|---|---|
| Slim | -slim |
~120 MiB | APIs, microservices, minimal footprint |
| Standard | (none) | ~250 MiB | Most Laravel/PHP apps (DEFAULT) |
| Chromium | -chromium |
~700 MiB | Browsershot, Dusk, PDF generation |
| Dev | -dev |
~750 MiB | Chromium + Xdebug, PCOV, SPX |
Complete Tag Examples
Every tag below also exists with the -v2 release-channel suffix (e.g.
8.5-trixie-slim-v2) — the recommended production pin.
Standard Tier (Default)
Most applications should use standard tier:
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-trixie
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-trixie
Slim Tier
For APIs and microservices with minimal footprint:
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-slim
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-trixie-slim
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-slim
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-trixie-slim
Chromium Tier
For Browsershot, Dusk, Puppeteer, and PDF generation:
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-chromium
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-trixie-chromium
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-chromium
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-trixie-chromium
Rootless Variants
All tiers support rootless execution (runs as www-data user):
# Standard + rootless
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-rootless
# Slim + rootless
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-slim-rootless
# Chromium + rootless
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-chromium-rootless
Version Matrix
| PHP Version | Debian 13 (Slim) | Debian 13 (Standard) | Debian 13 (Chromium) | Debian 13 (Dev) |
|---|---|---|---|---|
| 8.6 | ✅ | ✅ | ✅ | ✅ (no SPX) |
| 8.5 | ✅ | ✅ | ✅ | ✅ |
| 8.4 | ✅ | ✅ | ✅ | ✅ |
| 8.3 | ✅ | ✅ | ✅ | ✅ |
| 8.2 | ✅ | ✅ | ✅ | ✅ |
All variants also available with -rootless suffix.
Alias Tags
Two deliberately distinct concepts, both defined in versions.json:
- Newest (
php.newest, currently 8.5): the newest stable PHP. This is what thelatesttag follows, per Docker ecosystem convention. - Recommended default (
php.default, currently 8.5): what the documentation examples use and what we suggest for new projects. The two currently coincide; they are kept as separate concepts so the recommendation can deliberately trail a brand-new PHP minor while its extension ecosystem catches up.
Latest (follows php.newest):
latest→8.5-trixie8.5→8.5-trixie
Tier aliases:
slim→8.5-trixie-slimchromium→8.5-trixie-chromium
Don't use latest in production — pin a release channel tag
(8.5-trixie-v2) instead.
Deprecation Policy
Cbox follows a predictable deprecation schedule based on upstream EOL dates.
PHP has two lifecycle dates, and our policy keys off the second one:
- Active support end: php.net stops shipping bug fixes; security fixes continue for two more years. This is a normal, supported state — images keep receiving security updates, no warnings. Roughly half the PHP fleet is in this phase at any given time.
- Security support end: the date that matters. 90 days before it, images enter the deprecation warning phase; after it, the removal countdown starts.
Both dates live in versions.json (php.active_support_until and
php.security_support_until, sourced from
php.net/supported-versions).
Timeline
| Component | Removal After Security EOL | Warning Period |
|---|---|---|
| PHP | 6 months | 90 days |
| Debian | 3 months | 90 days |
| Node.js | 6 months | 90 days |
Current EOL Dates
Check versions.json for current support dates, or run:
./scripts/check-eol.sh
Deprecation Process
-
Warning Phase (90 days before removal):
- Deprecation notice added to image labels
- Warning in CI workflow output
- Documentation updated with migration guide
-
EOL Phase (upstream EOL reached):
- Images still built but marked deprecated
- No new features, security patches only
- Migration reminder in container startup
-
Removal Phase (after grace period):
- Images removed from registry
- Dockerfiles archived to
archive/branch - Final migration guide published
Checking Deprecation Status
# Check all EOL dates
./scripts/check-eol.sh
# Only show warnings
./scripts/check-eol.sh --warnings
# JSON output for CI
./scripts/check-eol.sh --json
Migration Guides
When a version is deprecated, migration guides are published at:
docs/troubleshooting/migration-guide.md- GitHub release notes
Examples by Use Case
Production (Standard Tier, Recommended)
services:
app:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie
API/Microservice (Slim Tier)
services:
api:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-slim
PDF Generation (Chromium Tier)
services:
pdf:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-chromium
Kubernetes (Rootless)
services:
app:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-trixie-rootless
See Also
- Available Images - Complete list of all images
- Choosing Your Image - Tiers, sizes, and when to use each