Documentation regarding configuration.

[SamMousa]

The configuration in /usr/local/etc/php-fpm.d/ is a bit unclear to me:

loot@92aa5b2f8217:/usr/local/etc# ls -la php-fpm.d/
total 56
drwxr-sr-x 2 root staff  4096 Jun  8 18:32 .
drwxrwsr-x 5 root staff  4096 Jun  8 18:32 ..
-rw-r--r-- 1 root staff   238 Jun  8 18:32 docker.conf
-rw-r--r-- 1 root staff 18508 Jun  8 18:32 www.conf
-rw-r--r-- 1 root staff 18508 Jun  8 18:32 www.conf.default
-rw-r--r-- 1 root staff    50 Jun  8 18:32 zz-docker.conf

What is the purpose of zz-docker.conf and docker.conf why are there 2 files?
Is this so that docker.conf gets includes before and zz-docker.conf after the pool configuration?

If that's the case doesn't it make sense to use aa-docker.conf for consistency?

Why would we always want to force the [www] pool to listen on [::]:9000?

It would be great if some documentation could be added regarding best / expected practices for changing configuration.

[orangelynx]

This is indeed very confusing, especially if one for example wanted to use unix sockets instead of TCP.

[tianon]

It would indeed be good to have this documented better -- I think the appropriate place would be a variant-fpm.md file in https://github.com/docker-library/docs/tree/3383325346b0ac532752d2f3725d1c654c3a3227/php (see busybox, debian, geonetwork, influxdb, openjdk, oraclelinux, python, sentry, traefik, wordpress, or znc for examples of how to structure that file). ❤️

Either adjusting or removing the Docker-provided configuration should be totally fine. I believe the rationale for us using zz-docker.conf was simply to ensure that file was sourced after the upstream-provided www.conf in order to overwrite the default listen address. It's perfectly reasonable for users of this image to replace that configuration completely with something that makes more sense for their use case, such as using Unix Sockets instead of TCP.

[tianon]

See also #498 for another minor bit that ought to be included in such a docs PR, namely that --cap-add SYS_PTRACE is necessary if request_slowlog_timeout is enabled.

[jelovac]

Any reason why zz- prefix is preferred instead of numeric prefix for config file ordering?

[tianon]

To make sure it comes after alphabetic configuration files (since [a-z] sorts lower than 0 lexicographically).

[aleskinen]

Why is listen 9000 added both in www.conf and zz-docker.conf files for pool www. I think latter is very unlogical and unnecessary.

[tianon]

@aleskinen if we look at their values, I think that should be a little more clear:

$ docker run --rm php:7.4-fpm sh -c "grep -rn 'listen =' /usr/local/etc/php-fpm.d/*.conf"
/usr/local/etc/php-fpm.d/www.conf:36:listen = 127.0.0.1:9000
/usr/local/etc/php-fpm.d/zz-docker.conf:5:listen = 9000

The one in www.conf is hard-coded to 127.0.0.1 (which won't be accessible outside the container, and thus is of very limited usefulness). Also, the most important thing to note is that www.conf is created/provided by PHP upstream, not something we create in this image. We only create docker.conf and zz-docker.conf:

php/fpm-Dockerfile-block-2

Lines 3 to 39 in a80762e

	RUN set -eux; \
	cd /usr/local/etc; \
	if [ -d php-fpm.d ]; then \
	# for some reason, upstream's php-fpm.conf.default has "include=NONE/etc/php-fpm.d/*.conf"
	sed 's!=NONE/!=!g' php-fpm.conf.default | tee php-fpm.conf > /dev/null; \
	cp php-fpm.d/www.conf.default php-fpm.d/www.conf; \
	else \
	# PHP 5.x doesn't use "include=" by default, so we'll create our own simple config that mimics PHP 7+ for consistency
	mkdir php-fpm.d; \
	cp php-fpm.conf.default php-fpm.d/www.conf; \
	{ \
	echo '[global]'; \
	echo 'include=etc/php-fpm.d/*.conf'; \
	} | tee php-fpm.conf; \
	fi; \
	{ \
	echo '[global]'; \
	echo 'error_log = /proc/self/fd/2'; \
	echo; echo '; https://github.com/docker-library/php/pull/725#issuecomment-443540114'; echo 'log_limit = 8192'; \
	echo; \
	echo '[www]'; \
	echo '; if we send this to /proc/self/fd/1, it never appears'; \
	echo 'access.log = /proc/self/fd/2'; \
	echo; \
	echo 'clear_env = no'; \
	echo; \
	echo '; Ensure worker stdout and stderr are sent to the main error log.'; \
	echo 'catch_workers_output = yes'; \
	echo 'decorate_workers_output = no'; \
	} | tee php-fpm.d/docker.conf; \
	{ \
	echo '[global]'; \
	echo 'daemonize = no'; \
	echo; \
	echo '[www]'; \
	echo 'listen = 9000'; \
	} | tee php-fpm.d/zz-docker.conf

The listen parameter in zz-docker.conf does not specify an IP specifically so that it will listen on all container IPs and be externally accessible (and thus usable from another container, such as one running NGINX to speak the FastCGI protocol and actually provide value).

This also makes it trivial for someone who wants the stock upstream configuration to revert to it (by deleting /usr/local/etc/php-fpm.d/*docker.conf).

[bronhy]

Any reason why 9000 port is used here as a default?

Since this is infra detail I would really recommend we use some other port. This way we need to change xdebug port for every project which has php-fpm setup.

[jdreesen]

XDebug changed its port to 9003 in version 3 ;) See: https://xdebug.org/docs/upgrade_guide#Step-Debugging