bixelro/php-apache repository overview

⁠PHP & Apache Docker image for Development and Testing

Dockerized PHP & Apache for local development and automated testing in continuous integration pipelines.

Build with support for Symfony 7+ and WordPress projects, contains most usual PHP versions, extensions, Composer 2, Symfony CLI and WordPress CLI.

The images are hosted on DockerHub with different tags for PHP versions.

⁠Floating Tags (Updated monthly with OS security patches)

• bixelro/php-apache:7.4
• bixelro/php-apache:8.1
• bixelro/php-apache:8.2
• bixelro/php-apache:8.3
• bixelro/php-apache:8.4
• bixelro/php-apache:8.5

⁠Version-Pinned Tags (Immutable releases)

To pin your environment to a specific release to prevent unexpected updates, append the release version (e.g. -v1.0.0 or -v2026.06.01):

• bixelro/php-apache:8.4-v1.0.0
• bixelro/php-apache:8.1-v2026.06.01

Warning! Do not add personal information or private source-code in the images, as they are publicly available.

⁠Getting started

To use with Docker Compose, add the service to the compose.yaml file:

services:
  web:
    image: bixelro/php-apache:8.4
    volumes:
      - .:/var/www/html
    ports:
      - "127.0.0.1:80:80"
      - "127.0.0.1:443:443"

Or directly as Docker container:

docker create -it \
    -v $(pwd):/var/www/html \
    -p 127.0.0.1:80:80 \
    -p 127.0.0.1:443:443 \
    --name project_web \
    bixelro/php-apache:8.4

⁠Configuration

⁠Project settings

If the project uses different settings (like a different Apache document root), they can be configured using environment variables either by creating a project Dockerfile extending the base one (more complex, as it requires a separate Docker image) or by providing the new values under environment in the compose.yaml file:

# compose.yaml
services:
  web:
    image: bixelro/php-apache:8.2
    environment:
      ENV_VAR_NAME: new-value

For plain Docker container, set the new values using the flag -e ENV_VAR_NAME=new-value on the docker create command.

⁠Developers preferences

Settings that are different amongst developers (like host ports) can be configured in a git-ignored compose.override.yaml file (adding a sample in project's code or in README.md is recommended):

# compose.override.yaml and compose.sample-override.yaml
services:
  web:
    volumes:
      # Mount SSH keys (read-only) to access private composer packages / Git repositories
      - ~/.ssh:/var/www/.ssh:ro
    # Details about port publishing: https://docs.docker.com/engine/network/#published-ports
    # Read the Important note on why you should include the host IP: "Publishing container ports is insecure by default"
    ports:
      - "127.0.0.1:YOUR_WEB_HTTP_PORT:80"
      - "127.0.0.1:YOUR_WEB_HTTPS_PORT:443"
    environment:
      ENV_VAR_NAME: override-value

For plain Docker container, add -p "127.0.0.1:8080:80" to customize ports and -e "ENV_VAR_NAME=override-value" for env vars to the docker create command.

⁠Environment variables reference

This is a list of the most commonly used settings that can be configured via environment variables, either added by this image or from underlying software:

⁠Apache

• APACHE_DOCUMENT_ROOT (default /var/www/html/public) - set the DocumentRoot for the default's site VirtualHost
• APACHE_RUN_USER and APACHE_RUN_GROUP (default: www-data) - more details about changing the default Apache user below

⁠PHP

• PHP_MEMORY_LIMIT (default 512M) - set a memory limit for PHP scripts, use -1 to disable (used to increase the PHP's default memory limit of only 128M)
• XDEBUG_MODE (default not set) - xDebug is turned off in app.ini for performance reasons, to enable Step Debugging and Development Helpers (improved var_dump, stack traces) and Code Coverage Analysis set it to debug,develop,coverage
• XDEBUG_CONFIG (default not set) - set various xDebug configs, like idekey (required by PhpStorm), optionally host and port (defaults are host.docker.internal and 9003): "idekey=PHPSTORM client_host=172.17.0.1 client_port=9000"
• PHP_IDE_CONFIG (default not set) - required by PhpStorm to resolve the path mappings: serverName=project-server-name, also see Debug a PHP CLI script | PhpStorm⁠ and Debugging with Symfony | API Platform⁠

The full list of xDebug settings are detailed at https://xdebug.org/docs/all_settings⁠.

⁠Composer

• COMPOSER_ALLOW_SUPERUSER (default 1) - allow root user to run composer scripts
• COMPOSER_MEMORY_LIMIT (default -1) - set or disable memory limits for composer

The full list of Composer settings are detailed at https://getcomposer.org/doc/03-cli.md#environment-variables⁠.

⁠Symfony

• SHELL_VERBOSITY (default 2) - increase console commands verbosity without manually setting --verbose to every Symfony console command (docs⁠)

⁠Makefile

• MAKEFILE_EXEC_WEB_DOCKER (default not set) - set empty string to run makefile commands inside Docker container
• MAKEFILE_EXEC_WEB_TEST_DOCKER (default not set) - set APP_ENV=test to run makefile commands in Docker with test env These need to be used by your project's makefile - check out the sample⁠.

⁠Running commands as Apache user

To run console commands as the Apache user (default www-data), pass the username to Docker's exec command using the -u flag: docker container/compose exec -itu www-data web [command]. Also add it in the project's makefile or README.md.

For Bitbucket Pipelines⁠ set the UID of the user in the run-as-user config under the image tag:

image:
  name: bixelro/php-apache:8.2
  run-as-user: 33 # UID of www-data user

⁠Customizations

⁠Upgrading the base image

The PHP & Apache DockerHub images are based on Debian 12 "Bookworm". Try to update the base image as soon as php:8.X-apache-trixie (based on Debian 13 "Trixie", available only as development distribution) is available.

⁠Changing default Apache user

If running commands as the default Apache user is not enough, you could try to change this user using the APACHE_RUN_USER and APACHE_RUN_GROUP env vars. You probably also need to chown a few other apache files, like /var/log/apache2 or /var/www/html which are owned by www-data in the base image⁠.