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:

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's channel tags are rebuilt weekly. 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.

Current status: -v1 is the current (and only) channel, built from main. A v2 channel was briefly opened for a unix-socket default and reversed on measurement - FastCGI keepalive on tcp beat it outright - so v2 waits for a genuinely breaking need. The release/v1 branch exists and is dormant.

# Recommended production pin: behavior locked, security patches current
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-v1

Image Tiers

Complete Tag Examples

Every tag below also exists with the -v1 release-channel suffix (e.g. 8.5-bookworm-slim-v1) — the recommended production pin.

Standard Tier (Default)

Most applications should use standard tier:

ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-bookworm
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-bookworm

Slim Tier

For APIs and microservices with minimal footprint:

ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-slim
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm-slim
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-bookworm-slim
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-bookworm-slim

Chromium Tier

For Browsershot, Dusk, Puppeteer, and PDF generation:

ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-chromium
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm-chromium
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-bookworm-chromium
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.2-bookworm-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-bookworm-rootless

# Slim + rootless
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-slim-rootless

# Chromium + rootless
ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-chromium-rootless

Version Matrix

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 the latest tag 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-bookworm
• 8.5 → 8.5-bookworm

Tier aliases:

• slim → 8.5-bookworm-slim
• chromium → 8.5-bookworm-chromium

Don't use latest in production — pin a release channel tag (8.5-bookworm-v1) 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 building weekly, 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

Current EOL Dates

Check versions.json for current support dates, or run:

./scripts/check-eol.sh

Deprecation Process

1. Warning Phase (90 days before removal):

   • Deprecation notice added to image labels
   • Warning in CI workflow output
   • Documentation updated with migration guide

2. EOL Phase (upstream EOL reached):

   • Images still built but marked deprecated
   • No new features, security patches only
   • Migration reminder in container startup

3. 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-bookworm

API/Microservice (Slim Tier)

services:
  api:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-slim

PDF Generation (Chromium Tier)

services:
  pdf:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-chromium

Kubernetes (Rootless)

services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.5-bookworm-rootless

See Also

• Available Images - Complete list of all images
• Choosing Your Image - Tiers, sizes, and when to use each