How to install extra caddy modules

[nickchomey]

I know that xcaddy is normally used to add extra modules, but its not clear to me how this could be done in the context of DDEV.

Official docs https://frankenphp.dev/docs/docker/#how-to-install-more-caddy-modules

It would be great if it could be documented in the README. Or, if it is not currently easy/possible, then it would be great to add support for such configurations. A primary reason to use Caddy is, like DDEV, its extensibility

[stasadev]

This can be done using multi-stage Docker build:

1. Create a file .ddev/web-build/prepend.Dockerfile.frankenphp-caddy-modules

   cat <<'EOF' > .ddev/web-build/prepend.Dockerfile.frankenphp-caddy-modules
   FROM dunglas/frankenphp:builder AS builder
   
   # Copy xcaddy in the builder image
   COPY --from=caddy:builder /usr/bin/xcaddy /usr/bin/xcaddy
   
   # CGO must be enabled to build FrankenPHP
   RUN CGO_ENABLED=1 \
       XCADDY_SETCAP=1 \
       XCADDY_GO_BUILD_FLAGS="-ldflags='-w -s' -tags=nobadger,nomysql,nopgx" \
       CGO_CFLAGS=$(php-config --includes) \
       CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" \
       xcaddy build \
           --output /usr/local/bin/frankenphp \
           --with github.com/dunglas/frankenphp=./ \
           --with github.com/dunglas/frankenphp/caddy=./caddy/ \
           --with github.com/dunglas/caddy-cbrotli \
           # Mercure and Vulcain are included in the official build, but feel free to remove them
           --with github.com/dunglas/mercure/caddy \
           --with github.com/dunglas/vulcain/caddy
           # Add extra Caddy modules here
   EOF

2. Create a file .ddev/web-build/Dockerfile.frankenphp-caddy-modules

   cat <<'EOF' > .ddev/web-build/Dockerfile.frankenphp-caddy-modules
   # Replace the official binary by the one contained your custom modules
   COPY --from=builder /usr/local/bin/frankenphp /usr/local/bin/frankenphp
   
   # Copy libraries from the builder
   COPY --from=builder /usr/local/lib/ /usr/local/lib/
   RUN ldconfig
   EOF

3. Create a file .ddev/docker-compose.frankenphp_builder.yaml

   cat <<'EOF' > .ddev/docker-compose.frankenphp_builder.yaml
   services:
     # These services are only used to pull the Docker images for offline use.
     frankenphp-builder:
       image: dunglas/frankenphp:builder
       profiles:
         - frankenphp-builder
     caddy-builder:
       image: caddy:builder
       profiles:
         - caddy-builder
   EOF

4. Run ddev utility rebuild

[nickchomey]

Thanks! I'll give it a try.

Though, I wonder if this could/should be made the default and expose some easy way to define the extra modules - eg an env var like {DDEV_FRANKENPHP_MODULES}

If you don't use it, nothing changes. If you do, it is easy to do.

[stasadev]

Though, I wonder if this could/should be made the default and expose some easy way to define the extra modules - eg an env var like {DDEV_FRANKENPHP_MODULES}

With Nginx, if you want to add a module, you install a package for it: https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/

I don't know if there is something similar for Caddy, but it would be much easier if there were frankenphp-module-* packages.

/cc @henderkes

[henderkes]

Unfortunately not, Go's shared libraries are essentially unusable, so Caddy only supports compiling plugins in statically.

Because FrankenPHP links against libphp.so however, you can compile your own version of it fairly easily. Install xcaddy, go and php-zts-devel and follow https://frankenphp.dev/docs/compile/#using-xcaddy

So:

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 \
    --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

[henderkes]

Hmm, small issue here is that brotli and watcher-c would be missing when using my packages. Perhaps I could create a frankenphp-devel package that installs go, xcaddy and the two libraries. System packages aren't really well-suited for variable, user defined build stuff.

[nickchomey]

Hmm, small issue here is that brotli and watcher-c would be missing when using my packages. Perhaps I could create a frankenphp-devel package that installs go, xcaddy and the two libraries.

This would be excellent.

I also wonder if Mercure and Vulcain could be excluded from the default, and then just added through whatever simple extension mechanism is created?

[henderkes]

The problem is that there can't be an extension mechanism, system packages and Go's static extension model just don't allow for that.

I'm already a bit unsure about offering a frankenphp-devel extension because it would only marginally simplify things and install stuff into non-default paths, which may just not be worth it to simplify something that still won't be completely setup-free.

As Vulcain and Mercure are part of the official releases (the packaging scripts are maintained in the frankenphp repo!), they stay by default.

[nickchomey]

What I mean by extension is the sort of pre.Dockerfile that stas listed above #64 (comment), but with a placeholder for env var or whatever to define extra modules to build

eg

--output frankenphp \ 
--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
{ DDEV_FRANKENPHP_EXTRA_MODULES } 

[henderkes]

Oh you mean on the Docker side, then absolutely.

[nickchomey]

I just tried the approach that stas shared and it built, but I just get Bad Gateway when visiting the site.

I tried using the version that Marc shared (which mostly just seems to add -zts and change a few of the --with lines), and the ddev utility rebuild fails.

Did I need to do anything in particular related to the existing ddev-frankenphp dockerfile, dockercompose file and Caddyfiles? Is the -zts necessary?

Thanks!

ps i didnt add any extra modules - was just trying to get it to work.

[henderkes]

Would you mind sharing the Dockerfile?

You need to install php-zts-devel for php-config-zts to be available.

[nickchomey]

The setup is the Dockerfiles etc from this addon's repo. (https://github.com/ddev/ddev-frankenphp/tree/main/web-build)

And then I also added what stas shared above. I dont know if I was supposed to remove the addon's files, or merge them somehow, or something else?

[nickchomey]

I would very much like to explore making a custom extension, but that requires compiling frankenphp from source. I was never able to figure out how to do any sort of custom build, via either stas' or marc's guidance. I don't seem to have any code leftover to share for guidance.

If anyone is able to solve this at some point, it would be very much appreciated

[henderkes]

I was able to solve it as best as possible, but that wasn't good enough to get upstreamed. Read more on why the (currently only) way it works is a poor choice: caddyserver/caddy#7488 (comment)

Tl;dr: complicated build process, rebuilds every single time FrankenPHP updates, extremely slow build process (likely 3-4 hours every time).

If you want a Go php extension your only realistic way is building from source and publishing your own Docker image with it. For my packages (or any packages, really) there's no good solution, even though it's technically simple to compile - all I do is:

sudo dnf install -y php-zts-devel brotli-devel go clang
# install e-dant/watcher C library
export CGO_ENABLED=1
export CC="clang" # only when using php 8.5+
export CGO_CLAGS="$(php-config-zts --includes)"
export CGO_LDFLAGS="-lpthread"
xcaddy build \
    --with github.com/dunglas/frankenphp \
    --with github.com/dunglas/frankenphp/caddy \
    # other standard modules
    --with github.com/youruser/yourrepo

[nickchomey]

If you want a Go php extension your only realistic way is building from source and publishing your own Docker image with it

Well, as far as I can tell, that's what DDEV exists to do. It has core images that you can then easily extend and it handles all the building, caching layers etc...

I dont quite understand how ddev-frankenphp works (and why, in particular, your zts builds were necessary), but it seems like there ought to be a relatively simple way to modify/extend the Dockerfille.frankenphp to allow for using xcaddy to either add existing caddy modules, or adding a golang php extension.

Stas suggested such an approach above, which would seemingly benefit from caching of different docker image stages/layers to allow for only building the php stuff once (if at all, if we can just use your prebuilt packages). But I couldn't get it working to add extra caddy modules

Though, I do wonder if a wasm approach (like the recently proposed frankenwasm) could work better, at least compared to making custom extensions (wouldn't do anything for existing caddy modules)