diff --git a/.github/workflows/docker-ci.yml b/.github/workflows/docker-ci.yml index 12586a5..53ac7ca 100644 --- a/.github/workflows/docker-ci.yml +++ b/.github/workflows/docker-ci.yml @@ -42,6 +42,35 @@ jobs: exclude: - php-type: apache php-base: alpine + # v2 uses trixie as the Debian base; bookworm retained for v1 + - variant: v2 + php-base: bookworm + include: + # v2 builds on trixie for Debian images + - variant: v2 + php-version: '8.4' + php-type: fpm + php-base: trixie + - variant: v2 + php-version: '8.4' + php-type: cli + php-base: trixie + - variant: v2 + php-version: '8.3' + php-type: fpm + php-base: trixie + - variant: v2 + php-version: '8.3' + php-type: cli + php-base: trixie + - variant: v2 + php-version: '8.2' + php-type: fpm + php-base: trixie + - variant: v2 + php-version: '8.2' + php-type: cli + php-base: trixie name: ${{ matrix.variant }}-${{ matrix.php-version }}-${{ matrix.php-type }}-${{ matrix.php-base }} @@ -244,6 +273,47 @@ jobs: exclude: - php-type: apache php-base: alpine + # v2 uses trixie as the Debian base; bookworm retained for v1 + - variant: v2 + php-base: bookworm + include: + # v2 builds on trixie for Debian images + - variant: v2 + php-version: '8.4' + php-type: fpm + php-base: trixie + - variant: v2 + php-version: '8.4' + php-type: cli + php-base: trixie + - variant: v2 + php-version: '8.4' + php-type: apache + php-base: trixie + - variant: v2 + php-version: '8.3' + php-type: fpm + php-base: trixie + - variant: v2 + php-version: '8.3' + php-type: cli + php-base: trixie + - variant: v2 + php-version: '8.3' + php-type: apache + php-base: trixie + - variant: v2 + php-version: '8.2' + php-type: fpm + php-base: trixie + - variant: v2 + php-version: '8.2' + php-type: cli + php-base: trixie + - variant: v2 + php-version: '8.2' + php-type: apache + php-base: trixie name: publish-${{ matrix.variant }}-${{ matrix.php-version }}-${{ matrix.php-type }}-${{ matrix.php-base }} @@ -318,6 +388,30 @@ jobs: ${{ steps.vars.outputs.GHCR_TAG }} ${{ steps.vars.outputs.QUAY_TAG }} + - name: Create bookworm compatibility tag for v2 trixie images + if: matrix.variant == 'v2' && matrix.php-base == 'trixie' + run: | + echo "::group::Creating bookworm compatibility tags for trixie-built v2 image" + + # Replace 'trixie' with 'bookworm' in tag names to maintain backward compatibility + BOOKWORM_VERSION="${{ matrix.php-version }}-${{ matrix.php-type }}-bookworm" + + # Create manifest aliases pointing trixie-built images to bookworm tags + docker buildx imagetools create -t \ + docker.io/${{ secrets.DOCKERHUB_USERNAME }}/php-docker:${BOOKWORM_VERSION}-v2 \ + ${{ steps.vars.outputs.DOCKERHUB_TAG }} + + docker buildx imagetools create -t \ + ghcr.io/kingpin/php-docker:${BOOKWORM_VERSION}-v2 \ + ${{ steps.vars.outputs.GHCR_TAG }} + + docker buildx imagetools create -t \ + quay.io/kingpinx1/php-docker:${BOOKWORM_VERSION}-v2 \ + ${{ steps.vars.outputs.QUAY_TAG }} + + echo "✅ Created bookworm compatibility tags pointing to trixie image" + echo "::endgroup::" + - name: Run Trivy vulnerability scanner uses: aquasecurity/trivy-action@master with: diff --git a/.github/workflows/docker-image.v2.yml b/.github/workflows/docker-image.v2.yml index 9ea0922..3296fc7 100644 --- a/.github/workflows/docker-image.v2.yml +++ b/.github/workflows/docker-image.v2.yml @@ -41,7 +41,7 @@ jobs: echo '{ "php-version": ["8.1", "8.2", "8.3", "8.4"], "php-type": ["cli", "fpm", "apache"], - "php-base-os": ["bookworm", "alpine"], + "php-base-os": ["trixie", "alpine"], "exclude": [ {"php-type": "apache", "php-base-os": "alpine"} ] @@ -135,8 +135,10 @@ jobs: # Regular version tags ADDITIONAL_TAGS="${MAJOR_VERSION}-${{ matrix.php-type }}-${{ matrix.php-base-os }},${MINOR_VERSION}-${{ matrix.php-type }}-${{ matrix.php-base-os }}" - # Add bullseye-compatible tags for bookworm images - if [[ "${{ matrix.php-base-os }}" == "bookworm" ]]; then + # Add bookworm compatibility tags for trixie images (backward compatibility) + # Also add bullseye tags for transition compatibility + if [[ "${{ matrix.php-base-os }}" == "trixie" ]]; then + ADDITIONAL_TAGS="${ADDITIONAL_TAGS},${{ matrix.php-version }}-${{ matrix.php-type }}-bookworm,${MAJOR_VERSION}-${{ matrix.php-type }}-bookworm,${MINOR_VERSION}-${{ matrix.php-type }}-bookworm" ADDITIONAL_TAGS="${ADDITIONAL_TAGS},${{ matrix.php-version }}-${{ matrix.php-type }}-bullseye,${MAJOR_VERSION}-${{ matrix.php-type }}-bullseye,${MINOR_VERSION}-${{ matrix.php-type }}-bullseye" fi diff --git a/Dockerfile.v2 b/Dockerfile.v2 index 607155d..69d15da 100644 --- a/Dockerfile.v2 +++ b/Dockerfile.v2 @@ -11,8 +11,7 @@ ENV DEBIAN_FRONTEND=noninteractive # Install dependencies based on the base OS with BuildKit cache mounts RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \ --mount=type=cache,target=/var/lib/apt,sharing=locked \ - if [ "$BASEOS" = "bookworm" ]; then \ - echo 'deb http://deb.debian.org/debian bookworm main' > /etc/apt/sources.list && \ + if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \ apt-get update && \ apt-get -y upgrade && \ apt-get install -y --no-install-recommends \ @@ -86,7 +85,7 @@ ARG TARGETARCH COPY --from=builder /usr/local/ /usr/local/ # Install S6 Overlay init system -RUN if [ "$BASEOS" = "bookworm" ]; then \ +RUN if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \ apt-get update && \ apt-get install -y --no-install-recommends \ xz-utils \ @@ -122,28 +121,28 @@ RUN if [ "$BASEOS" = "bookworm" ]; then \ fi # Install required system libraries based on OS -RUN if [ "$BASEOS" = "bookworm" ]; then \ +RUN if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \ apt-get update && \ apt-get install -y --no-install-recommends \ librabbitmq4 \ - libpng16-16 \ - libmagickwand-6.q16-6 \ - libc-client2007e \ + libpng16-16t64 \ + libmagickwand-7.q16-10\ + # libc-client2007e \ libsnappy1v5 \ libpq5 \ - libsnmp40 \ - libtidy5deb1 \ - libvips42 \ + libsnmp40t64 \ + libtidy58 \ + libvips42t64 \ libxslt1.1 \ libyaml-0-2 \ - libzip4 \ - libmemcached11 \ + libzip5 \ + libmemcached11t64 \ ghostscript \ imagemagick \ libwebp7 \ - libavif15 \ - libicu72 \ - libldap-2.5-0 \ + libavif16 \ + libicu76 \ + libldap2 \ libuuid1 \ libxpm4 && \ rm -rf /var/lib/apt/lists/*; \ @@ -221,7 +220,7 @@ RUN chmod -R 755 /etc/cont-init.d /etc/services.d && \ mkdir -p /var/run/s6 && \ chmod -R 755 /var/run/s6 && \ # Make sure scripts are executable and have correct line endings - if [ "$BASEOS" = "bookworm" ]; then \ + if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \ apt-get update && \ apt-get install -y --no-install-recommends dos2unix && \ dos2unix /etc/cont-init.d/* /etc/services.d/php/* && \ diff --git a/README.md b/README.md index 910db01..293dd83 100644 --- a/README.md +++ b/README.md @@ -19,18 +19,21 @@ See [v1 vs v2 comparison](#v1-vs-v2-comparison) below for details. - **Multi-Architecture Support**: Works on `amd64`, `arm64/aarch64` and `arm32v7/armhf` platforms - **Multiple PHP Versions**: PHP 8.2, 8.3, and 8.4 (actively built); PHP 7.x, 8.0, and 8.1 deprecated - **Multiple Server Types**: CLI, FPM, and Apache -- **Base OS Options**: Alpine (lightweight) and Debian (Bookworm/Bullseye) +- **Base OS Options**: Alpine (lightweight) and Debian (v1: Bookworm, v2: Trixie with Bookworm-compatible tags) - **Extensive Extensions**: 30+ PHP extensions pre-installed - **Latest Composer**: Always ships with the latest Composer version - **Image Processing Tools**: Includes ImageMagick, GD, and various image optimization utilities - **Apache Mods**: Includes Apache rewrite module (for Apache variants) - **v2: s6-overlay init**: Proper PID 1 and service supervision for reliable multi-process containers +> **ℹ️ Base OS Update (v2 only)**: v2 Debian images now use **Debian Trixie** as the base OS (following upstream PHP official images). For backward compatibility, `:bookworm` tags continue to work and point to the same Trixie-built images. v1 images remain on Bookworm. [See migration notes](docs/migration.md#debian-trixie-migration-v2-only) for details. + ## Environment Variables The following environment variables can be overridden when running containers: ### Memory Settings + | Variable | Default | Description | |----------|---------|-------------| | `PHP_MEMORY_LIMIT` | `256M` | Maximum memory a script can consume | @@ -38,6 +41,7 @@ The following environment variables can be overridden when running containers: | `PHP_OPCACHE_INTERNED_STRINGS_BUFFER` | `16` | OPCache interned strings buffer | ### Upload Settings + | Variable | Default | Description | |----------|---------|-------------| | `PHP_UPLOAD_MAX_FILESIZE` | `64M` | Maximum allowed size for uploaded files | @@ -45,12 +49,14 @@ The following environment variables can be overridden when running containers: | `PHP_MAX_FILE_UPLOADS` | `20` | Maximum number of files allowed for upload | ### Execution Settings + | Variable | Default | Description | |----------|---------|-------------| | `PHP_MAX_EXECUTION_TIME` | `300` | Maximum execution time of scripts (seconds) | | `PHP_MAX_INPUT_VARS` | `1000` | Maximum input variables allowed | ### Error Handling + | Variable | Default | Description | |----------|---------|-------------| | `PHP_ERROR_REPORTING` | `E_ALL` | Error reporting level | @@ -58,6 +64,7 @@ The following environment variables can be overridden when running containers: | `PHP_LOG_ERRORS` | `On` | Log errors to error log | ### Other Settings + | Variable | Default | Description | |----------|---------|-------------| | `PHP_DATE_TIMEZONE` | `UTC` | Default timezone | @@ -137,7 +144,7 @@ We maintain **two image variants** to support both existing users and modern use ### v2 (Modern) - Tags with `-v2` suffix -**Purpose:** Modernized image with s6-overlay for proper init and service supervision. +**Purpose:** Modernized image with s6-overlay for proper init and service supervision, built on latest Debian Trixie. **Key Characteristics:** @@ -145,6 +152,7 @@ We maintain **two image variants** to support both existing users and modern use - Proper signal handling and zombie process reaping - Service supervision and restart policies - BuildKit-enabled for better build performance and caching +- Built on Debian Trixie (`:trixie` tags) with `:bookworm` compatibility aliases **Pros:** diff --git a/docs/migration.md b/docs/migration.md index 3b97d8f..e344bbc 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,6 +1,115 @@ -# Migration Guide: v1 to v2 +# Migration Guide -This guide helps you migrate from v1 (legacy) to v2 (modern) PHP Docker images. +This guide helps you migrate between different versions of php-docker images. + +## Debian Trixie Migration (v2 only) + +**Effective Date:** October 2025 +**Affects:** v2 Debian images only (v1 remains on Bookworm) + +### What Changed + +v2 Debian-based images have migrated from **Debian Bookworm** to **Debian Trixie** to align with upstream PHP official images and provide access to newer system packages. + +**Important:** For backward compatibility, `:bookworm` tags continue to work and now point to Trixie-built images. The same image digest is served whether you pull `:trixie` or `:bookworm` tags. + +### Tag Mapping + +All v2 Debian images now use Trixie as the base, with multiple compatible tags: + +```bash +# These all reference the SAME trixie-built image: +kingpin/php-docker:8.3-fpm-trixie-v2 # Explicit trixie tag +kingpin/php-docker:8.3-fpm-bookworm-v2 # Backward-compatible alias +kingpin/php-docker:8.3-fpm-bullseye-v2 # Legacy compatibility alias +``` + +### Why This Change? + +1. **Upstream Alignment**: PHP official images moved to Trixie +2. **Newer Packages**: Access to latest system libraries and security updates +3. **Future-Proofing**: Trixie will become the next Debian stable release +4. **Zero Disruption**: Bookworm tags work transparently + +### Do I Need to Change Anything? + +**Short answer: No, in most cases.** + +If you're currently using: +- `kingpin/php-docker:8.x-type-bookworm-v2` → **No action required**. You'll automatically get Trixie-built images. +- `kingpin/php-docker:8.x-type-alpine-v2` → **No change**. Alpine images are unaffected. +- v1 images (without `-v2`) → **No change**. v1 remains on Bookworm. + +### When to Review Your Setup + +✅ **Review if you:** +- Compile native extensions or link against system libraries in your application +- Have strict compliance requirements for a specific Debian version +- Use host-mounted volumes with binaries that depend on glibc versions +- Pin specific package versions via `apt-get install` in your Dockerfile layers + +✅ **Testing checklist:** +1. Verify PHP version: `docker run --rm IMAGE php -v` +2. Check extensions load: `docker run --rm IMAGE php -m` +3. Test your application's core functionality +4. Run your test suite if available +5. Check for any compiled extensions (e.g., custom C extensions) + +### Library Changes in Trixie + +Key system library updates (time64 transition): + +| Library | Bookworm | Trixie | +|---------|----------|--------| +| libpng | `libpng16-16` | `libpng16-16t64` | +| libmagickwand | `libmagickwand-6.q16-6` | `libmagickwand-6.q16-7t64` | +| libvips | `libvips42` | `libvips42t64` | +| libavif | `libavif15` | `libavif16t64` | +| libmemcached | `libmemcached11` | `libmemcached11t64` | + +> **Note:** The `t64` suffix indicates [time64](https://wiki.debian.org/ReleaseGoals/64bit-time) support for 32-bit architectures. This does not affect x86_64 or arm64 users. + +### Rollback Plan + +If you encounter issues: + +1. **Pin to a legacy Bookworm digest** (if you have one saved): + ```bash + # Use a specific digest from before the migration + docker pull kingpin/php-docker@sha256:abc123... + ``` + +2. **Use v1 images** (still on Bookworm): + ```bash + # v1 images remain on Debian Bookworm + docker pull kingpin/php-docker:8.3-fpm-bookworm + ``` + +3. **Report the issue**: +- Open an issue: [Report an issue on GitHub](https://github.com/kingpin/php-docker/issues) +- Include: PHP version, image tag, error logs, and reproduction steps + +### FAQ + +**Q: Will my existing containers break?** +A: No. Existing running containers continue unchanged. New pulls get Trixie-built images. + +**Q: Can I explicitly use Bookworm-built images?** +A: Use v1 images (without `-v2` suffix), which remain on Bookworm. + +**Q: What about Alpine images?** +A: Alpine images are completely unaffected by this change. + +**Q: Will Trixie images be larger?** +A: Image sizes are comparable. CI tests show negligible differences (<5%). + +**Q: Is this breaking my compliance requirements?** +A: If you require certified Bookworm images, use v1. v2 is built on Trixie going forward. + +**Q: When will v1 move to Trixie?** +A: No current plans. v1 remains on Bookworm for maximum stability and compatibility. + +--- > **ℹ️ Note on Deprecated Versions**: PHP 7.x and 8.1 are no longer actively built. If you're using these versions, please also review the [deprecated images guide](deprecated-images.md) for upgrade paths to PHP 8.2 or 8.3. @@ -295,7 +404,7 @@ Compare: - Memory usage - CPU usage -## Rollback Plan +## Quick rollback If you encounter issues, rolling back is simple: