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.