Custom Caddy directives in serversideup/php FrankenPHP image – how to properly extend security headers and caddyfile.d?

[beliven-alex-zongaro]

Hi,

I'm using the serversideup/php FrankenPHP Docker image and trying to understand the correct way to extend Caddy configuration in a safe and supported way.

Context

The image already provides:

• a base /etc/frankenphp/Caddyfile
• a caddyfile.d/*.caddyfile import mechanism
• a security snippet with predefined headers
• an environment variable CADDY_SERVER_EXTRA_DIRECTIVES injected into the php-app-common block

What I'm trying to achieve

I need to add custom HTTP headers (for example CSP, Permissions-Policy, and some additional security headers) and ideally:

• keep them modular (not hardcoded in the main Caddyfile)
• avoid duplicating or overriding the existing security block
• be able to enable/disable or “activate” these custom snippets cleanly
• ensure compatibility with future image updates

What I've tried so far

1. Using caddyfile.d/*.caddyfile:

   • I can define snippets there
   • but I cannot reliably “activate” or attach them to the existing security block

2. Using CADDY_SERVER_EXTRA_DIRECTIVES:

   • works for simple header { ... } overrides
   • but it is fragile (formatting issues, newline problems, parsing errors)
   • cannot easily compose multiple reusable snippets

3. Trying to extend the existing security snippet:

   • seems not supported because header blocks do not merge
   • redefining security breaks or overrides existing behavior

Main issue

It is not clear what the intended extension mechanism is for:

• adding additional headers
• extending existing security configuration
• enabling custom snippets defined in caddyfile.d

Right now it feels like there is:

• file-based modularity (caddyfile.d)
• runtime injection (CADDY_SERVER_EXTRA_DIRECTIVES)
• but no clean way to combine or “activate” custom snippets into existing blocks

Questions

1. What is the recommended way to extend or override the security headers without editing the base image?
2. Is caddyfile.d intended only for standalone site/server directives, or can it safely extend existing snippets?
3. Is there a supported pattern for composing multiple reusable header blocks?
4. Is CADDY_SERVER_EXTRA_DIRECTIVES the only intended extension point for runtime customization?

Goal

I’m trying to understand the intended architecture so I can:

• keep configuration maintainable
• avoid breaking on image updates
• avoid fragile ENV-based hacks

Thanks in advance 👍