How to Override upload_max_filesize in a Docker Image
When configuring PHP within a Docker container, relying on environment variables like PHP_INI_SCAN_DIR is often insufficient for modifying core directives such as upload_max_filesize or post_max_size. The issue arises because the Dockerfile typically copies only specific configuration files into the standard location (/usr/local/etc/php/conf.d). If your application runs via CLI and successfully loads a custom .ini file, but your web server (like Apache or Nginx with PHP-FPM) fails to apply the same changes, it usually indicates that the web container is reading a different configuration source than expected.
In the scenario provided, the docker-compose.yml defines an environment variable PHP_INI_SCAN_DIR pointing to /usr/local/etc/php/custom.d. However, simply placing a file in that directory does not guarantee it will be loaded unless the PHP binary is explicitly configured to scan that path at startup. More critically, if you are trying to increase the upload limit for database dumps (as shown by the 2MB restriction on phpMyAdmin), you must ensure the directive exists in the active php.ini file used by the web server process, not just a separate custom directory that might be ignored due to precedence rules.
The most reliable method to override these settings permanently within a Docker image is to modify the actual php.ini file inside the container or mount a custom configuration file that takes precedence over the default one. When using Alpine-based images (common in official PHP containers), the default php.ini is often not present, and you must create it manually.
If your goal is to adjust these values for a specific service without rebuilding the entire image every time, mounting a custom php.ini via a volume is the standard approach. In your docker-compose.yml, ensure that the path to the mounted configuration file matches the entrypoint expectations of your PHP version. For example, if you are using Apache with PHP-FPM, you need to verify whether the web server passes the correct environment variables or if it requires a direct link to a custom config file.
A common pitfall is assuming that placing a file in /usr/local/etc/php/custom.d automatically overrides the default settings. While PHP_INI_SCAN_DIR tells PHP where to look for additional files, the order of precedence matters. Files found in custom.d are usually appended after the default php.ini, but if the default file contains conflicting settings or if the web server is configured to ignore external ini files (via LoadModule directives), your changes will be ignored.
To resolve the 2MB limit issue on phpMyAdmin specifically, check if the container for phpMyAdmin is using a base image that includes a full php.ini. If you mount ./app/config/php.ini:/usr/local/etc/php/php.ini, ensure that this file contains both upload_max_filesize and post_max_size set to your desired values (e.g., 64M). Additionally, for database uploads, remember that memory_limit might also need adjustment if the dump is processed entirely in memory.
If you prefer to bake these changes into the image itself rather than managing volumes, you can add a COPY command in your Dockerfile before the PHP package installation or use a RUN command to modify the existing configuration file. For instance:
COPY custom.ini /usr/local/etc/php/conf.d/custom.ini
# Or for full override
COPY php.ini /usr/local/etc/php/conf.d/php.ini
Ensure that the copied file is placed in a directory that PHP scans by default, or explicitly set PHP_INI_SCAN_DIR if using a minimal image. Also, verify that you are not hitting OS-level limits, such as ulimit -n, which could prevent large files from being uploaded even if PHP allows it.
If you are deploying with Laravel or similar frameworks, ensure that your application's configuration does not override these settings again. Sometimes framework-specific cache clears or artisan commands might reset configurations, so double-checking the effective configuration via a CLI run inside the container is essential:
php -i | grep upload_max_filesize
This command will show exactly what PHP sees at runtime, confirming whether your changes are active across all entry points.