Hi, I’m new into keycloak and I have some difficult to understand the development flow in order to customize keycloak. My use case is: I’ll distribute keycloak through docker images and I need to provide a whole new custom look and feel of user sign up and sign in flows.
question 1: in order to distribute keycloak as a container, I really need to build my own image from keycloak image and build it with my custom assets? For each new version of my custom assets (in this case I’m not considering only themes) I’ll need to generate a new keycloak custom image to deploy in my environments? Are there no options to avoid to maintain custom keycloak images?
question 2, about theme customization options and best practices: if I need to create a whole new html pages I need to package them as a jar file, deploy into /providers directory and build a new keycloack image? Could I have a separate frontend application calling keycloak REST APIs? (I’m not sure if Admin REST APIs have all endpoints needed).
What are your advices/best practices recommendations?
Thanks in advance
For theme customization see the docs here.
You don‘t have to package them as a JAR.
There‘s also no separate frontend app to run the authentication flow. That‘s not how OIDC works. When in doubt, please read the specs.
Depending on your needs and you environment, you don‘t necessarily create an own Keycloak Docker image. If you can live with mounting your theme resources in a volume to your container, you can do this. I prefer creating my own image with all the resources contained, so that I don‘t need a volume or other mount during runtime.
Thanks for you answer @dasniko !
I read these docs before, and deployment modes lead me to question, considering the best practices.
in production you may want to consider using an archive . An archive makes it simpler to have a versioned copy of the theme, especially when you have multiple instances of Keycloak for example with clustering.
So, in this scenario I need to build my custom imagem in order to run keycloak build command, right?
About frontend architecture and OIDC flows I understand. I’ll check in more depth the specs, thanks.
Starting with Keycloak 18, the Keycloak image will be auto-build as default.
In KC17, there was intially only an opt-out for having separate build and run configs.
In KC18, it’s default to auto-build the image, and if you want the two steps separated, it’s an opt-in to use them.
Don’t mix-up Keycloak image with a Docker image!
The Keycloak image is totally bound to the Quarkus requirements for having build-time and run-time configs.
Additionally: I had never the requirements to deploy themes as a JAR, I always deploy them as a directory (copy the directory to the Docker image during build).
But perhaps, there’s a use-case for it, don’t know. 
Thanks for tips! This strategy makes sense for me.
I have one more question that is still a bit confused for me when dealing with keycloak distribution in containers:
I always deploy them as a directory (copy the directory to the Docker image during build).
In your case, when you need to update the theme, do you build/create a new container image for it?
Could I just run the default keycloak docker image and map the themes directory to a volume?
(I understand that in this approach the downside is that I’ll have a startup time slower than the pre build one, but I’m not sure if its a bad practice)
Yes, with every update of any resource (no matter if theme or providers), a new Docker image is build. This is all completely automated and part of the CI/CD process, so I don‘t have to worry about.
But you can also run the pure Keycloak image directly and mounting volumes to it. Of course, why not? But then you have a dependency between the container and external resources/systems at runtime. This I want to avoid as best as I can.
Less dependencies, less worries.
Thanks for all explanation and help!