|
1 | | -# Migration Guide: v1 to v2 |
| 1 | +# Migration Guide |
2 | 2 |
|
3 | | -This guide helps you migrate from v1 (legacy) to v2 (modern) PHP Docker images. |
| 3 | +This guide helps you migrate between different versions of php-docker images. |
| 4 | + |
| 5 | +## Debian Trixie Migration (v2 only) |
| 6 | + |
| 7 | +**Effective Date:** October 2025 |
| 8 | +**Affects:** v2 Debian images only (v1 remains on Bookworm) |
| 9 | + |
| 10 | +### What Changed |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +**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. |
| 15 | + |
| 16 | +### Tag Mapping |
| 17 | + |
| 18 | +All v2 Debian images now use Trixie as the base, with multiple compatible tags: |
| 19 | + |
| 20 | +```bash |
| 21 | +# These all reference the SAME trixie-built image: |
| 22 | +kingpin/php-docker:8.3-fpm-trixie-v2 # Explicit trixie tag |
| 23 | +kingpin/php-docker:8.3-fpm-bookworm-v2 # Backward-compatible alias |
| 24 | +kingpin/php-docker:8.3-fpm-bullseye-v2 # Legacy compatibility alias |
| 25 | +``` |
| 26 | + |
| 27 | +### Why This Change? |
| 28 | + |
| 29 | +1. **Upstream Alignment**: PHP official images moved to Trixie |
| 30 | +2. **Newer Packages**: Access to latest system libraries and security updates |
| 31 | +3. **Future-Proofing**: Trixie will become the next Debian stable release |
| 32 | +4. **Zero Disruption**: Bookworm tags work transparently |
| 33 | + |
| 34 | +### Do I Need to Change Anything? |
| 35 | + |
| 36 | +**Short answer: No, in most cases.** |
| 37 | + |
| 38 | +If you're currently using: |
| 39 | +- `kingpin/php-docker:8.x-type-bookworm-v2` → **No action required**. You'll automatically get Trixie-built images. |
| 40 | +- `kingpin/php-docker:8.x-type-alpine-v2` → **No change**. Alpine images are unaffected. |
| 41 | +- v1 images (without `-v2`) → **No change**. v1 remains on Bookworm. |
| 42 | + |
| 43 | +### When to Review Your Setup |
| 44 | + |
| 45 | +✅ **Review if you:** |
| 46 | +- Compile native extensions or link against system libraries in your application |
| 47 | +- Have strict compliance requirements for a specific Debian version |
| 48 | +- Use host-mounted volumes with binaries that depend on glibc versions |
| 49 | +- Pin specific package versions via `apt-get install` in your Dockerfile layers |
| 50 | + |
| 51 | +✅ **Testing checklist:** |
| 52 | +1. Verify PHP version: `docker run --rm IMAGE php -v` |
| 53 | +2. Check extensions load: `docker run --rm IMAGE php -m` |
| 54 | +3. Test your application's core functionality |
| 55 | +4. Run your test suite if available |
| 56 | +5. Check for any compiled extensions (e.g., custom C extensions) |
| 57 | + |
| 58 | +### Library Changes in Trixie |
| 59 | + |
| 60 | +Key system library updates (time64 transition): |
| 61 | + |
| 62 | +| Library | Bookworm | Trixie | |
| 63 | +|---------|----------|--------| |
| 64 | +| libpng | `libpng16-16` | `libpng16-16t64` | |
| 65 | +| libmagickwand | `libmagickwand-6.q16-6` | `libmagickwand-6.q16-7t64` | |
| 66 | +| libvips | `libvips42` | `libvips42t64` | |
| 67 | +| libavif | `libavif15` | `libavif16t64` | |
| 68 | +| libmemcached | `libmemcached11` | `libmemcached11t64` | |
| 69 | + |
| 70 | +> **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. |
| 71 | +
|
| 72 | +### Rollback Plan |
| 73 | + |
| 74 | +If you encounter issues: |
| 75 | + |
| 76 | +1. **Pin to a legacy Bookworm digest** (if you have one saved): |
| 77 | + ```bash |
| 78 | + # Use a specific digest from before the migration |
| 79 | + docker pull kingpin/php-docker@sha256:abc123... |
| 80 | + ``` |
| 81 | + |
| 82 | +2. **Use v1 images** (still on Bookworm): |
| 83 | + ```bash |
| 84 | + # v1 images remain on Debian Bookworm |
| 85 | + docker pull kingpin/php-docker:8.3-fpm-bookworm |
| 86 | + ``` |
| 87 | + |
| 88 | +3. **Report the issue**: |
| 89 | + - Open an issue: https://github.com/kingpin/php-docker/issues |
| 90 | + - Include: PHP version, image tag, error logs, and reproduction steps |
| 91 | + |
| 92 | +### FAQ |
| 93 | + |
| 94 | +**Q: Will my existing containers break?** |
| 95 | +A: No. Existing running containers continue unchanged. New pulls get Trixie-built images. |
| 96 | + |
| 97 | +**Q: Can I explicitly use Bookworm-built images?** |
| 98 | +A: Use v1 images (without `-v2` suffix), which remain on Bookworm. |
| 99 | + |
| 100 | +**Q: What about Alpine images?** |
| 101 | +A: Alpine images are completely unaffected by this change. |
| 102 | + |
| 103 | +**Q: Will Trixie images be larger?** |
| 104 | +A: Image sizes are comparable. CI tests show negligible differences (<5%). |
| 105 | + |
| 106 | +**Q: Is this breaking my compliance requirements?** |
| 107 | +A: If you require certified Bookworm images, use v1. v2 is built on Trixie going forward. |
| 108 | + |
| 109 | +**Q: When will v1 move to Trixie?** |
| 110 | +A: No current plans. v1 remains on Bookworm for maximum stability and compatibility. |
| 111 | + |
| 112 | +--- |
4 | 113 |
|
5 | 114 | > **ℹ️ 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. |
6 | 115 |
|
|
0 commit comments