Here's a short version of what I have done.

I created a custom container image, pretty much according to the documentation. In the documentation, on the last line of the Dockerfile it reads ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]. That's what I put in my custom image.

Then I tried to use this custom image with Keycloak Testcontainer. It failed to start my custom Keycloak image. The error message was:

Unmatched argument at index 1: 'build'
Try 'kc.sh build --help' for more information on the available options.

Keycloak Testcontainer manages to start the default image from quay.io just fine, so apparently there was something wrong with my custom image. After a long study I figured that Keycloak Testcontainer adds some command arguments with what it starts the container. Those include start and --auto-build among others. As a result the command to execute in my custom image becomes something like /opt/keycloak/bin/kc.sh start start --auto-build.

After that I tried what happens if I try to run the standalone distribution of Keycloak 17 with the command kc.sh start start --auto-build. And lo and behold, there it is the most confusing error message: Unmatched argument at index 1: 'build'.

I think there are a few places that could be improved:

1. The "build your own image" documentation could be improved. It could emphasize that the demonstrated entry point (ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]) is not the same that is in the official image (which is ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]). As a result, the custom image can't be started with the same arguments as the official image. Alternatively the documentation could use the same entry point in the example as the official image uses, i.e. without the start argument. That way the custom image could work as a drop-in replacement for the official image.
2. When providing more than one command to the kc.sh script, it should print a clear error that many commands were given and that's not allowed. The current behavior is most confusing, at least with the start start --auto-build arguments.
   • I could argue that the Unmatched argument at index 1: 'build' is a pretty bad error message in any situation. "Unmatched"? When matching against what? Perhaps some whitelist somewhere? "At index 1"? This index refers to what? Some list somewhere? Is it a 0 or 1 based indexing scheme? Overall, very confusing.