behance/docker-php repository overview

⁠docker-php

Provides a pre-wired, configurable PHP + Nginx setup across multiple runtime versions.

Integrated with Behance’s docker-nginx⁠

Available on Docker Hub⁠.

⁠Quick-start

• docker run behance/docker-php:7.4-alpine "php" "-v"
• docker run behance/docker-php:7.4" "php" "-v"
• docker run behance/docker-php:8.0" "php" "-v"

Adding code to runtime, see here⁠. PHP tuning and configuration, see here⁠. Nginx tuning and configuration, see here⁠. Adding startup logic, basic⁠ or advanced⁠.

⁠Container tag scheme: PHP_MAJOR.PHP_MINOR(-Major.Minor.Patch)(-variant)

• PHP_MAJOR.PHP_MINOR, required. Engine versions of PHP. ex. docker-php:8.0
• (Major.Minor.Patch), optional. Semantically versioned container provisioning code. ex. docker-php:7.4-13.4.0.
• (-variant), optional. Alpine variants are slim versions of the container. ex. docker-php:7.4-alpine.

⁠Includes

• Nginx⁠ HTTP server
• PHP / PHP-FPM: primary runtime
• S6⁠: PID 1 zombie reaping, startup coordination, shutdown signal transferal. Nginx and PHP are preconfigured to shutdown as gracefully as possible.
• Goss⁠: for serverspec-like testing. Run goss -g /tests/php-fpm/{PHP_MAJOR.PHP_MINOR}(-variant).goss.yaml to validate any configuration updates
• Ubuntu (default) or Alpine OS base⁠
• Common PHP extensions:

For extension customization, including enabling and disabling defaults, see here⁠

^ - not available on -alpine variant ~ - disabled by default

• apcu
• bcmath
• bz2
• calendar
• ctype
• curl
• date
• dom
• exif
• cgi-fcgi
• gd
• iconv
• igbinary
• intl
• json
• mbstring
• memcache ^
• memcached
• msgpack
• mysqli
• mysqlnd
• newrelic ~ (activates with env variables)
• opcache
• openssl
• pcntl
• pdo
• pdo_mysql
• pdo_pgsql ~
• pgsql ~
• phar
• posix
• redis ~
• shmop
• SimpleXML
• sockets
• sysvmsg
• sysvsem
• sysvshm
• tokenizer
• xdebug ~
• xml
• xmlreader
• xmlwriter
• yaml ~
• zip
• zlib

⁠Expectations

Sample Dockerfile

FROM behance/docker-php:8.0

# (optional, recommended) Verify everything is in order from the parent
RUN goss -g /tests/php-fpm/8.0.goss.yaml validate && /aufs_hack.sh

# Layer local code into runtime
COPY ./ /app/

# Done!

• Local code should be copied into /app, for example: COPY ./ /app/

• Nginx is pre-configured to use a front controller PHP file (entrypoint) a front controller called index.php within a public folder. /app/public/index.php

• Dev Mode (no ENV variables): PHP's opcache is enabled, and is set to check files for updates. Code can be developed locally in Docker by mounting into the /app folder. For example, the docker-compose.yml syntax:

volumes:
   - ./:/app

• Production Mode [recommended]: using ENV variable, CFG_APP_DEBUG=0. Container becomes immutable, PHP's opcache is configured to not check files for updates.
• NOTE: Nginx is exposed and bound to an unprivileged port, 8080.

⁠Monitoring

• NewRelic APM: automatically enabled by adding providing environment variables REPLACE_NEWRELIC_APP and REPLACE_NEWRELIC_LICENSE
• NewRelic Distributed Tracing: Before enabling distributed tracing be sure to read the transition guide⁠. To enable this set NEWRELIC_TRACING_ENABLED to true.
• NewRelic Loglevel: you can override the NewRelic newrelic.loglevel and newrelic.daemon.loglevel config defaults (currently warning) to something more verbose for debugging purposes by setting environment variable NEWRELIC_LOGLEVEL to an available option (options include info, debug, verbosedebug)
• NewRelic Special: NewRelic has a newrelic.special config for special debug (sometimes requested by the NewRelic support team), you can turn that option on as directed by NewRelic support by setting enviroment variable NEWRELIC_SPECIAL to whatever value requested.
• PHP-FPM Status: available only inside container at /__status. Application healthcheck can pull PHP-FPM statistics from http://127.0.0.1/__status?json. To open to more clients than local, add more allow statements in __status location block in $CONF_NGINX_SITE(/etc/nginx/sites-available/default)
• Nginx Status: available only inside container at /__nginx_status. Application healthcheck can pull nginx statistics from http://127.0.0.1/__nginx_status. To open to more clients than local, add more allow statements in __nginx_status location block in $CONF_NGINX_SITE (/etc/nginx/sites-available/default)

⁠Downstream Configuration

⁠PHP Extensions

A variety of common extensions are included, and can be enabled or disabled as needed.

⁠To enable a built-in and disabled extension:

On Ubuntu (default):

# phpenmod XXX

On Alpine variant:

# sed -i "s/^;ext/ext/" $CONF_PHPMODS/XXX.ini

⁠To disable a built-in extension:

On Ubuntu (default):

# phpdismod XXX

On Alpine variant:

# sed -i "s/ext/;ext/" $CONF_PHPMODS/XXX.ini

⁠Environment variables

Environment variables can be used to tune various PHP-FPM and Nginx parameters without baking them in.

See parent(s) for additional configuration options:

• docker-nginx⁠
• docker-base⁠

⁠Testing

• Requires bash, docker, and dgoss (link⁠)

To test locally, run PHP_VARIANT=8.0 ./test.sh {docker engine IP}.

This will:

• Build a single container PHP_VARIANT (ex. 7.4-alpine, 7.4, 8.0)
• Leverages Goss⁠ to confirm package, config, and extension installation
• Validates a large file upload
• Boots container with specific NewRelic configuration overrides

⁠Release Management

Github actions provide the machinery for testing (ci.yaml) and producing tags distributed through Docker Hub (publish.yaml). Testing will confirm that nginx is able to serve content in various configurations, but also that it can terminate TLS with self-signed certificates. Once a tested and approved PR is merged, simply cutting a new semantically-versioned tag will generate the a matrix of tagged builds. See Container tag scheme above.

Platform support is available for multiple architectures:

• linux/amd64: Ubuntu and Alpine variants
• linux/arm64: Ubuntu variants-only

To add new variant based on a new Dockerfile, add an entry to matrix.props within ./github/workflows YAML files.

⁠Github Actions: Simulation

docker-nginx uses Github Actions for CI/CD. Simulated workflows can be achieved locally with act. All commands must be executes from repository root.

Pre-reqs: tested on Mac

1. Docker Desktop⁠
2. act⁠

Pull request simulation: executes successfully, but only on ARM devices (ex. Apple M1). ARM emulation through QEMU on X64 machines does not implement the full kernel functionality required by nginx at this time.

• act pull_request

Publish simulation: executes, but fails (intentionally) without credentials

• act