jakubboucek/lamp-devstack-php repository overview

⁠LAMP devstack Docker images (PHP part)

Images for local development in LAMP devstack⁠

⁠Why use prebuilt images instead of building your own?

These images are designed for efficient local development of small to medium-sized PHP projects typically deployed on shared hosting environments. Key benefits of this approach include:

• Instant startup with no build step – the images are publicly available and ready to use; simply launch them using docker compose.
• Supports multiple projects with different PHP versions – easily switch container versions without modifying the base image.
• Resource reuse and disk space efficiency – all projects share the same base image, minimizing storage footprint and startup time.
• Optimized for common development needs – the environments closely mirror typical shared hosting setups, without unnecessary extras.
• Runtime customization without rebuilding – key runtime parameters can be configured via environment variables at container start time (see below⁠), eliminating the need to build custom images for minor environment tweaks.

Instead of maintaining and rebuilding separate images for each project, you can rely on a consistent, maintained set of base images designed to cover most standard development workflows — with no setup overhead and minimal resource duplication.

⁠Main features

• architecture: linux/amd64
• current PHP versions: 8.5, 8.4, 8.3, 8.2 and 8.1
• unsupported PHP versions also available: 8.0, 7.4, 7.3, 7.2, 7.1, 7.0, 5.6, 5.5 and 5.4 (with limited stability, unoptimized, unmaintained)
• current version of Apache 2.4 (in non-CLI images)
• current version of Xdebug 3.4 (in debug images)
• current version of SPX Profiler⁠ (in debug images)
• extra PHP extensions: bmath⁠, bz2⁠, calendar⁠, exif⁠, gd⁠ with PNG, WebP, AVIF, FreeType fonts support gettext⁠, gmp⁠, intl⁠, memcached⁠, mysqli⁠, pdo_mysql⁠, opcache⁠, pcntl⁠, semaphore⁠, sockets⁠, soap⁠, sodium⁠, xsl⁠ and zip⁠
• Apache modules: expires⁠, headers⁠ and rewrite⁠
• Apache DocumentRoot changed to: /var/www/html/www (configurable by ENV⁠)
• PHP image comes with Composer 2.8+⁠ and Git 2.49+⁠ to use it in guest shell
• timezones are correctly supported
• optimized for small image size and short load times

⁠Removed extensions

Certain PHP extensions have been intentionally excluded from these images because they are deprecated and interfere with compatibility with important updates of other components.

⁠Basic usage

Copy the docker-compose.yml⁠ file (download⁠) to your project's root (you don't need to clone/download the whole repo, just copy that one file).

Call docker compose up. After docker container runs, your project will be served at http://localhost:8080/⁠.

Only /www subdirectory from your project is served but PHP scripts have access to the whole project's root.
That means only the /www subdirectory is publicly accessible from web, not your whole application.

Example:

my_project/                 <-- project's root
    docker-compose.yml      <-- docker config from this repository
    www/                    <-- Document Root, accessible at http://localhost:8080/
        index.php           <-- your PHP app
        logo.png            <-- accessible at http://localhost:8080/logo.png
        gallery/
            photo1.jpg      <-- accessible at http://localhost:8080/gallery/photo1.jpg
    vendor/
        autoload.php        <-- not accessible but PHP can via: require(__DIR__ . '/../vendor/autoload.php')

⁠Version tags

Images are tagged by the cascaded SemVer:

• jakubboucek/lamp-devstack-php:latest – means latest available stable PHP image,
• jakubboucek/lamp-devstack-php:8 – represents the highest PHP image of 8 version, but lower than 9.0.0,
• jakubboucek/lamp-devstack-php:8.5 – represents the highest PHP image of 8.5 version, but lower than 8.6.0,
• jakubboucek/lamp-devstack-php:8.5.0 – represents most specific PHP image, directly version 8.5.0.

Legacy PHP images are tagged using different strategy, only latest revision for each minor version is available, use -legacy tag suffix:

• jakubboucek/lamp-devstack-php:8.0-legacy
• jakubboucek/lamp-devstack-php:7.4-legacy
• jakubboucek/lamp-devstack-php:7.3-legacy
• jakubboucek/lamp-devstack-php:7.2-legacy
• jakubboucek/lamp-devstack-php:7.1-legacy
• jakubboucek/lamp-devstack-php:7.0-legacy
• jakubboucek/lamp-devstack-php:5.6-legacy
• jakubboucek/lamp-devstack-php:5.5-legacy
• jakubboucek/lamp-devstack-php:5.4-legacy-fixed

All PHP images have alternative variants with XDebug extension preinstalled, use -debug tag suffix, example:

• jakubboucek/lamp-devstack-php:debug
• jakubboucek/lamp-devstack-php:8-debug
• jakubboucek/lamp-devstack-php:8.5-debug
• jakubboucek/lamp-devstack-php:8.5.0-debug
• jakubboucek/lamp-devstack-php:7.4-legacy-debug

All PHP images also have alternative CLI variants, use -cli tag suffix, example:

• jakubboucek/lamp-devstack-php:cli
• jakubboucek/lamp-devstack-php:8-cli
• jakubboucek/lamp-devstack-php:8.5-cli
• jakubboucek/lamp-devstack-php:8.5.0-cli
• jakubboucek/lamp-devstack-php:7.4-legacy-cli

⁠Extended configuration

⁠PHP configuration

Certain php.ini directives⁠ can be modified without manipulating the image content, using environment variables. It can be defined in docker run command or in docker-compose.yml file.

Configurable directives:

• PHP_ERROR_REPORTING - change the error_reporting directive⁠ (default value: 32767, means E_ALL)
• PHP_DISPLAY_ERRORS - change the display_errors directive⁠ (default value: 1)
• PHP_DISPLAY_STARTUP_ERRORS - change the display_startup_errors directive⁠ (default value: 1, on PHP 7: 0)
• PHP_ERROR_LOG – change the error_log directive⁠ (default value: empty)
• PHP_LOG_ERRORS – change the log_errors directive⁠ (default value: 0)
• PHP_MAX_EXECUTION_TIME – change the max_execution_time directive⁠ (default value: 30)
• PHP_MEMORY_LIMIT – change the memory_limit directive⁠ (default value: 2G)
• PHP_SESSION_SAVE_PATH – change the session.save_path directive⁠ (default value: empty)
• PHP_OPCACHE_BLACKLIST_FILENAME – change the opcache.blacklist_filename directive⁠ (default value: empty)
• PHP_OPCACHE_ENABLE – change the opcache.enable directive⁠ (default value: 1)
• PHP_OPCACHE_ENABLE_CLI – change the opcache.enable_cli directive⁠ (default value: 0)
• PHP_OPCACHE_JIT – change the opcache.jit directive⁠ (default value: tracing, on PHP 8.4 changed⁠: disable)
• PHP_OPCACHE_JIT_BUFFER_SIZE – change the opcache.jit_buffer_size directive⁠ (default value: 0, on PHP 8.4 changed⁠: 64M)
• PHP_OPCACHE_MEMORY_CONSUPTION – change the opcache.memory_consumption directive⁠ (default value: 128)
• PHP_OPCACHE_PRELOAD – change the opcache.preload directive⁠ (default value: empty)
• PHP_OPCACHE_PRELOAD_USER – change the opcache.preload_user directive⁠ (default value: empty)
• PHP_OPCACHE_VALIDATE_TIMESTAMPS – change the opcache.validate_timestamps directive⁠ (default value: 1)
• PHP_OPCACHE_REVALIDATE_FREQ – change the opcache.revalidate_freq directive⁠ (default value: 2)

Example for docker run command:

docker run --rm -e PHP_MEMORY_LIMIT=1G jakubboucek/lamp-devstack-php php -i

Example docker-compose.yml file:

environment:
    PHP_MEMORY_LIMIT: 1G

⁠Document Root

Create custom APACHE_DOCUMENT_ROOT environment variable with the path to Document Root as the value.

You can also specify it directly with docker run:

docker run -it --rm -e APACHE_DOCUMENT_ROOT=/my-web jakubboucek/lamp-devstack-php

You can also put it to your docker-compose.yml file:

environment:
    APACHE_DOCUMENT_ROOT: "/my-web"

⁠Timezone

The default timezone is not defined (UTC will be used). You can modify the default timezone by setting the TZ environment variable to the desired timezone name (e.g., Europe/Prague).

It can also be specified directly with docker run:

docker run -it --rm -e TZ=Europe/Prague jakubboucek/lamp-devstack-php

Or in your docker-compose.yml file:

environment:
    TZ: Europe/Prague

The TZ environment variable is recognized by Linux tools as well. By creating the variable you modify the default timezone for the whole Linux operating system, and also PHP.

At PHP since version 8.2 is TZ variable set to 'UTC' by default (otherwise is empty).

⁠Temporary, upload and session storage directory

PHP is using native Linux temporary directory for all own temporary files (including session and upload storage). This image does not provide any custom way to modify them. You can use the TEMPDIR environment variable to modify all of them.

You can specify it directly with docker run:

docker run -it --rm -e TEMPDIR=/var/www/temp jakubboucek/lamp-devstack-php

Or in the docker-compose.yml file:

environment:
  TEMPDIR: /var/www/temp

Note: The directory MUST already exists and MUST be writable for all users (0777), otherwise PHP can be unstable or can lose data (e.g. sessions data). Moving the temporary directory to a volume shared with the Host can have a big impact on performance.

The TEMPDIR environment variable is also recognized by Linux tools. By setting that variable you modify the default temporary directory for the whole Linux operating system, PHP, and also MySQL.

⁠Apache – listening port

Apache is by default configured to listening on TCP port 80. You can use the PORT environment variable to modify port number where is apache listening to HTTP Requests.

Note: This variable is affect Apache runtime only. When you change port value, don't forget manually publish that port to host, when you want to access it from here or expose port to use at network.

You can specify it directly with docker run:

docker run -it --rm -e PORT=8080 -p 8080:8080 jakubboucek/lamp-devstack-php

Or in the docker-compose.yml file:

ports:
  - "8080:8080"
environment:
  PORT: 8080

The PORT environment variable is also used by most known services (e.g. Google Cloud Run⁠).

⁠Other PHP configurations

Settings other than those listed above can be set in your INI file. You can add it to /usr/local/etc/php/conf.d directory using Volume mounting⁠ without building a custom image.

Create custom.ini file in your project's root, for example:

sendmail_from = [email protected]

Mount the file to the container using the volume directive in your docker-compose.yml file:

volumes:
  - "./custom.ini:/usr/local/etc/php/conf.d/custom.ini"

Check available docker-compose.yml⁠ file for an example of how to use the volume directive.

⁠Advanced usage

⁠Xdebug

I've also prepared a PHP image with Xdebug. Use docker-compose-debug.yml⁠ (download⁠) instead (copy and rename it to docker-compose.yml).

Xdebug is not started by default, you must call requests with relevant trigger⁠ (tip: how to fire triggers from your browser⁠).

These features are enabled in Xdebug:

• Profiler⁠
• Step Debugger⁠
• Tracing⁠

Profiler a Tracing outputs are saved to /var/www/html/log directory inside Container. Output files are propagated to the Host to log/ directory (this directory must be manually created first).

You can change the output directory through XDEBUG_CONFIG environment variable with output_dir parameter.

In docker-compose.yml⁠ file modify the environment section, for example:

environment:
    XDEBUG_CONFIG: "client_host=host.docker.internal output_dir=/another/dir"
    #                                                ^^^^^^^^^^^^^^^^^^^^^^^

Starting with Xdebug 3.3, Profiler a Tracing outputs are compressed with GZip. You can turn off GZip compression through the XDEBUG_CONFIG environment variable with use_compression parameter and value false.

In docker-compose.yml⁠ file modify environment section, for example:

environment:
    XDEBUG_CONFIG: "client_host=host.docker.internal use_compression=false"
    #                                                ^^^^^^^^^^^^^^^^^^^^^

⁠SPX Profiler

In Debug images is prepared also SPX Profiler⁠ extension. It is not enabled by default, you must enable it via PHP_SPX_ENABLED environment variable.

In docker-compose.yml⁠ file, add PHP_SPX_ENABLED environment variable with value 1:

environment:
    PHP_SPX_ENABLED: 1

Than is profiler available at URL: http://localhost:8080/?SPX_KEY=dev&SPX_UI_URI=/⁠

⁠Debugging CLI with PhpStorm

With PhpStorm, you can also debug CLI scripts. First, you need to set the Server name, PhpStorm requires it for path mapping⁠.

In docker-compose.yml⁠ file, add PHP_IDE_CONFIG environment variable with serverName parameter:

environment:
    PHP_IDE_CONFIG: "serverName=docker-cli"