How to reload FrankenPHP without restart to reresolve root directory

[alexander-schranz]

What happened?

In our Setup Infrastructure deployments and Code Deployments are completely separated in our setup.

We deploy code via deployer and need to reload FrankenPHP but FrankenPHP seems not work or reresolve the target directory.

Deployment via Deployer works via changed symlink. So webserver is targeting the current/public directory. And current is a symlink to the specific release so directory structure is something like:

 - current -> releases/1
 - releases
    - 1
       - public
          - index.php (Return `<h1>Release 1</h1>`)
          - test.txt (Return `Release 1`)
    - 2
       - public
          - index.php (Return `<h1>Release 2</h1>`)
          - test.txt (Return `Release 2`)

Here a reproducer repo, I'm running:

https://github.com/alexander-schranz/frankenphp-deployer-releases-reproducer

It basically works by switch the symlink:

# Release 1
ln -sfn releases/1 current
# Todo: reload FrankenPHP without any downtime?
curl -XGET http://127.0.0.1:8082/
curl http://127.0.0.1:8082/test.txt

# Release 2
ln -sfn releases/2 current
# Todo: reload FrankenPHP without any downtime?
curl -XGET http://127.0.0.1:8082/
curl http://127.0.0.1:8082/test.txt

Why the reproducer is created on MacOS, the Online / Production Infrastructure runs on Debian and FrankenPHP inside Docker. So the issue is unrelated to the OS or Static vs Docker Builds.

What I tried:

./frankenphp reload

        # change resolve_root_symlink seems not effect frankenphp or caddy:
        resolve_root_symlink true
        resolve_root_symlink false

./frankenphp adapt --config Caddyfile | curl localhost:2019/load \
   -H "Content-Type: application/json" \
   -d @-

curl -X POST http://localhost:2019/frankenphp/workers/restart

Build Type

Static binary

Worker Mode

No

Operating System

macOS

CPU Architecture

Apple Silicon

PHP configuration

phpinfo() output

Reproducer uses binary from `curl https://frankenphp.dev/install.sh | sh`
without any custom php.ini.

Why we want use hard settings for opcache.

	# Recommended settings for Opcache used also for Nginx:
	# php_ini opcache.enable 1
	# php_ini opcache.revalidate_path 0
	# php_ini opcache.memory_consumption 256
	# php_ini opcache.max_accelerated_files 32531
	# php_ini opcache.validate_timestamps 0
	# php_ini opcache.revalidate_freq 0
	# php_ini realpath_cache_size 0
	# php_ini realpath_cache_ttl 600

Relevant log output

Relevant log output

[henderkes]

resolve_root_symlink must be false.

Then, instead of frankenphp reload, you must use frankenphp reload --force if you did not change the Caddyfile. Caddy checks for config changes before attempting the reload.

[henderkes]

Actually, we should properly document this as it comes up quite often. Maybe a section about "zero downtime deployments".

[alexander-schranz]

Then, instead of frankenphp reload, you must use frankenphp reload --force

@henderkes Awesome, thank you that does work.

resolve_root_symlink must be false.

This seems in my case has no effects or seems not be required? Can you provide some information on why you think this matters?

Actually, we should properly document this as it comes up quite often. Maybe a section about "zero downtime deployments".

That would be great.

PS: If used caddy without frankenphp instead php-fpm it recommends use resolve_root_symlink here: https://deployer.org/docs/8.x/avoid-php-fpm-reloading#fix-for-caddy (which is default if I understand this PR)

Do you know why this works with caddy+php-fpm but not with franken? I understand the case for worker mode but maybe out it would be possible to have it working out of the box in classic mode as it seems work in caddy + php-fpm?

[henderkes]

Actually with a php runtime restart (which reload --force does), the resolve_root_symlink setting shouldn't matter. It also reloads the configuration so it will resolve the roots again.