FrankenPHP v1.10: install from .deb while adding extra Caddy modules

[scoueille]

Hi FrankenPHP team 👋

I’m trying to deploy FrankenPHP on multiple servers and I’d like to install it from .deb packages (Debian 13 target), but I also need to compile in an additional Caddy storage module to coordinate certificate/storage state across servers (S3 backend).

In practice, what I’m trying to add is one of these modules (I wanted to test both):

• github.com/ss098/certmagic-s3
• github.com/techknowlogick/certmagic-s3

What I used to do

With older FrankenPHP versions, I used Docker buildx with something like:

• BUILD_PACKAGES=y
• XCADDY_ARGS=... (to add extra modules)

It would run build-static.sh then build-packages.sh and produce installable packages.

What changed (FrankenPHP v1.10)

On FrankenPHP v1.10, build-packages.sh is no longer present, and I can’t find the replacement workflow to:

1. build FrankenPHP with extra Caddy modules, and
2. still get a clean .deb package.

I’ve seen the official .deb repository here: https://debs.henderkes.com/
…but (unless I missed something) those packages don’t include optional extra Caddy modules.

I’d therefore like to know whether there is an official method to produce Debian packages (.deb) with extra Caddy modules.

Thanks!
Sébastien

[henderkes]

You can use the scripts in the package folder to create your own debian packages that depend on php-zts-embed very easily.

sudo apt install php-zts-devel
sudo ln -s /usr/lib/libphp-zts.so /usr/lib/libphp.so
xcaddy build ...
-> got your custom frankenphp binary that uses the system provided libphp-zts-8X.so

[henderkes]

Thinking about it, you have no reason to even generate deb packages yourself in this case. Just install my deb packages on each client, then swap out the frankenphp binary with the one you compiled (or save it to /usr/bin/frankenphp-extra and sudo systemctl edit frankenphp.service to use that binary instead).

I think in your specific use-case, switching to Docker may be even simpler, though.

[scoueille]

Hi Marc, and thanks a lot for your reply.

That makes sense! In our first tests we did rebuild FrankenPHP with xcaddy, and then we swaped the caddy binary, but using a .deb package is really cleaner and more convenient for operations.

My main concern with “install the .deb then swap the binary” is that we’d have to redo it after every apt upgrade (and make sure we never forget). I’d also always have some doubt about whether I compiled it with the right options/flags.

On top of that, I need to harden the systems as much as possible, so I’m not a big fan of using Docker here (it would increase the attack surface and the amount of stuff to secure).

For completeness: I tested FrankenPHP 1.9.1 compiled with the techknowlogick/certmagic-s3 plugin, but that version crashes as described in this bug: #1760 (Main process exited, code=killed, status=11/SEGV)

When I tried to move to 1.10.1 to continue testing, I noticed the packaging script was gone. Also, I haven’t been able to compile the binary successfully: I’m hitting the same error as the CI run here (it fails on libxslt):
https://github.com/php/frankenphp/actions/runs/20083095560/job/57614610018

Would it be possible for you to share the script / workflow you use to generate your .deb packages?

Thanks again!

[henderkes]

My main concern with “install the .deb then swap the binary” is that we’d have to redo it after every apt upgrade (and make sure we never forget).

Then you should compile your own FrankenPHP binary and edit the systemd script like I suggested. Of course you still need to remember to recompile the new FrankenPHP version, but you had to do the same with the previous deb packages, which didn't auto update either.

Also, I haven’t been able to compile the binary successfully: I’m hitting the same error as the CI run here (it fails on libxslt)

Libxslt updated to break with lower libxml2 versions, you'd need to build from source without using prebuilt libraries or wait a few days.

That being said, you should not use the static binaries for production. Link against libphp-zts-84.so dynamically like I said with xcaddy. Then you get automatic php updates through our deb repo.

[henderkes]

sudo apt install php-zts-devel sudo ln -s /usr/lib/libphp-zts.so /usr/lib/libphp.so xcaddy build ... -> got your custom frankenphp binary that uses the system provided libphp-zts-8X.so

Follow this, then https://frankenphp.dev/docs/compile/

the xcaddy command:

CGO_ENABLED=1 \ XCADDY_GO_BUILD_FLAGS="-ldflags='-w -s' -tags=nobadger,nomysql,nopgx" \ CGO_CFLAGS=$(php-config-zts --includes) \ CGO_LDFLAGS="$(php-config-zts --ldflags) $(php-config-zts --libs)" \ xcaddy build \ --output frankenphp-scouelle \ --with github.com/dunglas/frankenphp/caddy \ --with github.com/dunglas/mercure/caddy \ --with github.com/dunglas/vulcain/caddy \ --with github.com/dunglas/caddy-cbrotli # Add extra Caddy modules and FrankenPHP extensions here

Then copy that to /usr/local/bin and systemctl edit frankenphp.service to use it.

Will need to install libbrotli-dev and compile watcher-c manually before.

[scoueille]

Thanks a lot for the clarifications, and especially for the advice about not using static binaries in production, that makes perfect sense.

I managed to successfully recompile FrankenPHP with xcaddy, linking dynamically against PHP using php-zts-devel and php-zts-embed.

In case this helps someone else, here’s what I ended up doing after compiling watcher-c manually and installing the required PHP extensions via your php-zts-* packages:

• Create the symlink (I didn’t have /usr/lib/libphp-zts.so, only the versioned one, not sure if that’s expected):

sudo ln -s /usr/lib/libphp-zts-84.so /usr/lib/libphp.so

• Build FrankenPHP with xcaddy:

CGO_ENABLED=1 \
XCADDY_GO_BUILD_FLAGS="-ldflags='-w -s' -tags=nobadger,nomysql,nopgx" \
CGO_CFLAGS=$(php-config-zts --includes) \
CGO_LDFLAGS="$(php-config-zts --ldflags) $(php-config-zts --libs)" \
xcaddy build \
  --output frankenphp-extra \
  --with github.com/dunglas/frankenphp/caddy \
  --with github.com/dunglas/caddy-cbrotli \
  --with github.com/dunglas/mercure/caddy \
  --with github.com/dunglas/vulcain/caddy \
  --with github.com/techknowlogick/certmagic-s3

• Keep both binaries cleanly using dpkg-divert and update-alternatives:

sudo dpkg-divert --divert /usr/bin/frankenphp.default --rename /usr/bin/frankenphp
sudo mv ./frankenphp-extra /usr/bin/frankenphp.custom

sudo update-alternatives --install /usr/bin/frankenphp frankenphp /usr/bin/frankenphp.default 10
sudo update-alternatives --install /usr/bin/frankenphp frankenphp /usr/bin/frankenphp.custom 50

This way it’s easy to switch between the stock and custom binaries using update-alternatives.

I’m currently testing the S3 storage plugin. If I end up not being able to make everything work reliably together, I’m also considering another approach: using a classic Caddy (with the S3 plugin built in) as a reverse proxy in front of FrankenPHP. Since Caddy uses GoReleaser, producing a .deb with extra plugins is fairly straightforward there.

[henderkes]

Happy to hear it worked out for you! That's similar to what I was suggesting.

I may have forgotten about libphp-zts.so, it should typically be a symlink to the versioned one after installing php-zts-devel. I'll look at it next week.