Best practices for custom theme with Docker deploy?

Hello all,

I was wondering if I could get some advice/feedback on best practices for deploying custom themes with a Keycloak cluster running in Docker containers. For context, we’re running Keycloak in ECS, roughly following this architecture, but I think the question applies to any containerized deploy of Keycloak.

What is the recommended/best way to deploy custom themes in a Docker environment?

The most simple/obvious way would be to just write a Dockerfile that bakes the theme folders into the container image, and deploy that. However, that seems really heavyweight to me. We change one line of CSS and we have to build and push/pull 700 MBs worth of new container image?

I noticed that the official Keycloak Docker images support running custom startup scripts, and that there is a documented format for distributing Keycloak themes as a zip archive.

We’re considering doing the following:

  • Deploy the themes as a zip archive to some publicly-accessible webhost.
  • Add a startup script to our Docker image that installs the theme bundle using --command="module add" at run time.
  • Trigger the replacement of containers inside ECS to pick up the new theme.

To my mind, this seems like a good approach because it preserves the notion of immutable containers with no shared state (except the database), and uses built-in features of Keycloak and the official Keycloak Docker image, but avoids repeated heavyweight Docker builds for trivial cosmetic changes.

Anyone have feedback or suggestions? I’m curious how other teams are handling this problem.

Here is an example which works for us :

FROM jboss/keycloak:11.0.3
COPY ./theme/xxx-base /opt/jboss/keycloak/themes/xxx-base
COPY ./theme/yyy-patient /opt/jboss/keycloak/themes/yyy-patient
COPY ./theme/zzz-base /opt/jboss/keycloak/themes/zzz-base

COPY ./target/hug-keycloak-jar-with-dependencies.jar /opt/jboss/keycloak/providers/hug-keycloak.jar

USER root
RUN curl -L --output /opt/jboss/keycloak/providers/keycloak-metrics-spi-2.1.0.jar

USER 1000
ENTRYPOINT [ “/opt/jboss/tools/” ]
CMD ["-b", “”]