How to turn off the Keycloak theme cache

Keycloak implements a cache mechanism that is really useful in production instances to improve the overall system performances, but steps into your work when you develop themes.

When theme caching is enabled you always have to restart Keycloak to see the changes you make to Freemarker templates. This is incredibly annoying, but fortunately there are different solutions that you can adopt to solve the issue.

Disable the theme caching in standalone.xml

I suggest this method if you installed Keycloak locally, without using the Docker image. There is an easier way to disable caching using the Docker image that I will explain later in this post.

Open your standalone.xml configuration file and look for <theme>, then set the following values:

<theme>
    <staticMaxAge>-1</staticMaxAge>
    <cacheThemes>false</cacheThemes>
    <cacheTemplates>false</cacheTemplates>
    ...
</theme>

Restart Keycloak, now you only need to refresh your page to see the changes you make to the templates.

Disable theme caching using the jboss-cli

If you want to disable the theme caching on a running installation you can use the jboss-cli.

Ensure Keycloak is running, then enter the keycloak folder of your installation and start the cli with the following command (on linux):

bin/jboss-cli.sh

This will open a prompt saying that you are disconnected. To connect, simply type:

[disconnected /] connect

The prompt should now look like this:

[standalone@localhost:9990 /]

Run the following commands to disable the theme caching:

[standalone@localhost:9990 /] /subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)
[standalone@localhost:9990 /] /subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)
[standalone@localhost:9990 /] /subsystem=keycloak-server/theme=defaults/:write-attribute(name=staticMaxAge,value=-1)

Finally, reload your Keycloak instance to apply the changes:

standalone@localhost:9990 /] reload

Run exit to close the jboss-cli, theme caching should be disabled.

Disable theme caching with a script

This method is my recommendation in case you use the Keycloak Docker image.

Similarly to the previous solution we are going to use the scripting capability of Keycloak to run some commands on initialisation. It’s my default configuration when I develop themes.

Create a new file locally called disable-theme-cache.cli and paste the following commands:

embed-server --std-out=echo --server-config=standalone-ha.xml
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)
/subsystem=keycloak-server/theme=defaults/:write-attribute(name=staticMaxAge,value=-1)
stop-embedded-server

Now open your docker-compose.yml file and mount the directory where you have this script as a volume in the Keycloak container, like this:

keycloak:
    ....
    volumes:
      - ../scripts/disable-theme-cache.cli:/opt/jboss/startup-scripts/disable-theme-cache.cli

Restart Keycloak, if everything works fine you should be able to see the following message somewhere in the logs:

Executing cli script: /opt/jboss/startup-scripts/disable-theme-cache.cli

This means caching has been disabled.

Conclusion

There are different ways to disable the Keycloack theme cache and each of them has a different use case. I personally prefer using Docker during theme development and I use the third method, but in case you have different requirements this article should cover for them.