Migration Guide
Migration Guide
Complete guide for migrating to Cbox from other PHP Docker solutions.
V1 to V2 (unpublished candidate)
V2 changes the OS from Debian 12 Bookworm to Debian 13 Trixie. Rebuild the
application image from scratch; do not apt-dist-upgrade a v1 container.
The intended pin changes from 8.5-bookworm-v1 to 8.5-trixie-v2 once v2
has been published. PHP 8.2, 8.3, 8.4, 8.5 and 8.6 have independent source
locks; CLI and FPM for a series use the same archive. PHP 8.6 is built with
ZTS (thread safety), as the official 8.6 recipe is, and some of its extensions
are pinned to upstream commits until they tag a release - see
PHP 8.6 extension sources.
- Recompile custom PHP extensions and native libraries against Trixie. Do not
copy extension
.sofiles from v1: ICU, ImageMagick and other library ABIs changed. ImageMagick is now 7; validate image rendering in your application. AVIF and HEIC encoders are installed explicitly because Trixie makes them optional packages; local and native CI checks exercise image roundtrips. - The PHP
vipsextension is removed. Use GD/ImageMagick or a separate libvips service if your workload needs it. - Node remains on the 22 LTS line (22.23.4); npm moves from bundled npm 10
to separately pinned npm 12.2.2 to remove its known vulnerable dependencies.
Re-run your application's
npm ciand build scripts before adopting v2. - Match your application's Playwright version to
tools.playwrightinversions.json, or install that application's browser revision yourself. Composer and Playwright are pinned; apt-only patches do not update them. SSL_MODE=fullnow redirects HTTP to HTTPS while retaining loopback/healthz. Check ingress headers, application URLs and health probes.- FPM dynamic-pool defaults now follow the final autotune environment. This
fixes startup failure in small containers where autotuning chose fewer
workers than the previous hard-coded spare-worker count. With manual
PHP_FPM_MAX_CHILDREN=1, default start/spare counts now fit that pool. Explicit user-provided start/spare values are retained. - Validate rootless permissions and your actual host kernel/container runtime. Local macOS/OrbStack tests do not certify old RHEL host seccomp/Landlock behavior. Keep the previous immutable application digest for rollback.
The first v2 build is full. Subsequent OS-only patches require matching source, configuration, dependencies, architecture and Debian-suite labels. A new PHP patch or other changed build input forces a full build; unchanged apt indexes and completed build chains avoid scheduling needless work. See the source-build implementation for local tests.
Quick Migration Matrix
| From | Main Differences | Migration Complexity |
|---|---|---|
| ServerSideUp | Architecture similar, different env vars | ⚡ Easy |
| Bitnami | Different user, paths, and structure | 🔧 Moderate |
| Official PHP | Need to add Nginx, different config | 🔨 Complex |
| Custom | Varies by implementation | 🎯 Variable |
From ServerSideUp Images
Key Differences
| Aspect | ServerSideUp | Cbox |
|---|---|---|
| Process Manager | S6 Overlay | Cbox Init (Go) |
| User | www-data (fixed) | www-data/nginx (OS-dependent) |
| Env Prefix | PHP_ |
PHP_, NGINX_ |
| Health Checks | Built-in | Built-in |
Migration Steps
1. Update image name:
# Before (ServerSideUp)
services:
app:
image: serversideup/php:8.3-fpm-nginx
# After (Cbox)
services:
app:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-v2
2. Update environment variables:
# Most variables work the same, but check:
# ServerSideUp
AUTORUN_ENABLED=true
AUTORUN_LARAVEL_STORAGE_LINK=true
# Cbox
LARAVEL_OPTIMIZE_ENABLED=true
# (storage link runs automatically)
3. Update volume paths (if different):
# Paths are the same
volumes:
- ./:/var/www/html
4. Test and verify:
docker-compose build
docker-compose up -d
docker-compose logs -f app
ServerSideUp → Cbox Env Mapping
| ServerSideUp | Cbox | Notes |
|---|---|---|
PHP_MEMORY_LIMIT |
PHP_MEMORY_LIMIT |
Same |
PHP_OPCACHE_ENABLE |
PHP_OPCACHE_ENABLE |
Same |
AUTORUN_ENABLED |
N/A | Always enabled |
AUTORUN_LARAVEL_STORAGE_LINK |
N/A | Automatic |
From Bitnami Images
Key Differences
| Aspect | Bitnami | Cbox |
|---|---|---|
| User | 1001 |
www-data (82/33) |
| Install Path | /opt/bitnami |
/var/www/html |
| Config Location | /opt/bitnami/php/etc |
/usr/local/etc/php |
| Process Manager | Custom scripts | Cbox Init (Go) |
Migration Steps
1. Update image and paths:
# Before (Bitnami)
services:
app:
image: bitnami/php-fpm:8.3
volumes:
- ./:/app
# After (Cbox)
services:
app:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-v2
volumes:
- ./:/var/www/html
2. Update user permissions:
# Bitnami uses UID 1001
# Cbox uses www-data (UID 33 on Debian)
# Update file ownership
chown -R 33:33 . # www-data on Debian
3. Update configuration paths:
# Before (Bitnami)
volumes:
- ./php.ini:/opt/bitnami/php/etc/php.ini
# After (Cbox)
volumes:
- ./php.ini:/usr/local/etc/php/conf.d/zz-custom.ini
4. Update database host:
# Before (Bitnami often uses specific service names)
DB_HOST=mariadb
# After (Cbox - use your service name)
DB_HOST=mysql
From Official PHP Images
Key Differences
| Aspect | Official PHP | Cbox |
|---|---|---|
| Web Server | None (FPM only) | Nginx included |
| Extensions | Minimal | 40+ pre-installed |
| Configuration | Manual | Environment variables |
| Production Ready | Requires work | Ready to use |
Migration Steps
1. Simplify your docker-compose.yml:
# Before (Official PHP - separate services)
services:
php:
image: php:8.3-fpm
volumes:
- ./:/var/www/html
nginx:
image: nginx:trixie
volumes:
- ./:/var/www/html
- ./nginx.conf:/etc/nginx/conf.d/default.conf
# After (Cbox - combined)
services:
app:
image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-v2
ports:
- "8000:80"
volumes:
- ./:/var/www/html
2. Remove custom Dockerfile (if only installing extensions):
# Before - Custom Dockerfile needed for extensions
FROM php:8.3-fpm
RUN docker-php-ext-install pdo_mysql redis opcache gd
# After - Extensions pre-installed, no Dockerfile needed!
# Just use: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-v2
3. Update configuration method:
# Before - Mount custom php.ini
volumes:
- ./php.ini:/usr/local/etc/php/php.ini
# After - Use environment variables (easier)
environment:
- PHP_MEMORY_LIMIT=256M
- PHP_OPCACHE_VALIDATE_TIMESTAMPS=0
# Or still mount if needed
volumes:
- ./php.ini:/usr/local/etc/php/conf.d/zz-custom.ini
From Custom Images
Assessment Checklist
Evaluate your custom image:
- Which PHP extensions are installed?
- Custom PHP configuration?
- Custom Nginx configuration?
- System packages installed?
- Custom initialization scripts?
- Process management setup?
Migration Strategy
Option 1: Use Cbox Directly (if possible)
Check if Cbox includes everything you need:
# Check included extensions
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-v2 php -m
Option 2: Extend Cbox Image
For additional requirements:
FROM ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.3-trixie-v2
# Add your custom extensions
RUN apt-get update && apt-get install -y ffmpeg
# Add custom configurations
COPY docker/php/custom.ini /usr/local/etc/php/conf.d/zz-custom.ini
COPY docker/nginx/custom.conf /etc/nginx/conf.d/custom.conf
# Add initialization scripts
COPY docker-entrypoint-init.d/ /docker-entrypoint-init.d/
Framework-Specific Migrations
Laravel
# Add Laravel-specific settings
environment:
- LARAVEL_SCHEDULER=true
- LARAVEL_OPTIMIZE_ENABLED=true
- LARAVEL_QUEUE=true
Symfony
# Add Symfony-specific settings
environment:
- APP_ENV=prod
Symfony is auto-detected (via bin/console + symfony.lock) and var/
permissions are fixed automatically. For cache warmup on startup, drop an init
script into /docker-entrypoint-init.d/ — it runs before the services start:
# docker-entrypoint-init.d/10-warmup.sh
#!/bin/sh
php bin/console cache:warmup --env=prod
WordPress
# WordPress configuration
environment:
- WORDPRESS_DB_HOST=mysql
- WORDPRESS_DB_NAME=wordpress
- WORDPRESS_DB_USER=wordpress
- WORDPRESS_DB_PASSWORD=${DB_PASSWORD}
Post-Migration Checklist
After migrating:
- All services start successfully
- Application is accessible
- Database connections work
- File permissions correct
- Cache/sessions working
- Scheduled tasks running (if applicable)
- Queue workers running (if applicable)
- Static assets loading
- Logs accessible and clean
- Performance acceptable
Common Migration Issues
Issue: File Permission Errors
# Check current ownership
docker-compose exec app ls -la /var/www/html
# Fix permissions
docker-compose exec app chown -R www-data:www-data /var/www/html/storage
Issue: Database Connection Failed
# Update to use Docker service name
DB_HOST=mysql # Not 'localhost'!
Issue: Missing PHP Extension
# Check if extension exists
docker-compose exec app php -m | grep extension_name
# If missing, extend the image (see docs/advanced/extending-images.md)
Migration Support
Need help with migration?
- Check examples: See guides section for your framework
- Search issues: GitHub Issues
- Ask community: GitHub Discussions
Related Documentation
- Extending Images - Customization guide
- Laravel Guide - Laravel-specific setup
- Environment Variables - Configuration options
- Common Issues - Troubleshooting
Migration questions? Ask in GitHub Discussions.