8:39 a.m.
TL:DR; WildFly documentation has not kept pace with the flexibility we added with Galleon
feature packs and Glow. How can we improve it?
I have been using several WildFly feature packs the last few weeks in which I've not
been involved in and I noticed a few improvements we could make to our documentation that
would greatly reduce the friction and make for a better developer experience.
For a traditional way to use WildFly (donwload the server zip, build your deployments and
deploy it), the documentation experience mostly comes from 2 places:
* the WildFly model reference[1] that describes what WildFly is providing
* the Jakarta EE[2] & MicroProfile[3] APIs that we are using to write the
applications
However, with the use of Galleon feature packs, the documentation and model reference are
no longer captured and deliver to the developers.
If I want to use the API X in my applications, what are the feature packs & layers
that I need to provision for WildFly?
WildFly Glow has introduced a set of rules that binds layers to these APIs.
So for example if I'm using the MicroProfile Health API[4], this API is enabled by the
"microprofile-config" layer.
These rules are only used within WildFly Glow but I think there is values in exposing them
to developers.
Ideally, when I want to try a new API, I would have liked to answers questions like:
* Which layer do I need to provision when I'm using the Langchain4J API?
* Which feature pack is providing that layer?
* What are the resources contributed by this layer?
* What are the layers that provides LLM integrations?
* For the ollama layer that I want to use, how can I configure these resources?
(I'm using the WildFly AI feature pack but this is just an example of the friction
I've encountered)
We have all the code in place to answer these questions but they are sprinkled in many Git
repositories and you must know what you are looking for to get answers:
* Which layer do I need to provision when I'm using the Langchain4J API?
=> the "ai" layer (as described in
https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/main/ai-fe...)
* Which feature pack is providing that layer?
=> the "org.wildfly:wildfly-ai-galleon-pack" is providing this layer (as
described at
https://github.com/wildfly-extras/wildfly-ai-feature-pack/tree/main?tab=r...)
* What are the resources contributed by this layer?
=> the "ai" spec defines them at
https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/main/ai-fe...
but we don't have a generated model reference for them
* What are the layers that provides LLM integrations?
=> they are listed at
https://github.com/wildfly-extras/wildfly-ai-feature-pack/tree/main/ai-fe...
* For the ollama layer that I want to use, how can I configure these resources?
=> the spec defines them at
https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/main/ai-fe...
but I don’t have their model reference
=> the default Ollama model is llama3.1:8b and can be configured with the expresion
"org.wildfly.ai.ollama.chat.model.name" (using the
ORG_WILDFLY_AI_OLLAMA_CHAT_MODEL_NAME env var) or with the OLLAMA_CHAT_MODEL_NAME env var
(from
https://github.com/wildfly-extras/wildfly-ai-feature-pack/blob/b0a59b9ba6...)
I don't have a strong opinion for where I want to go but looking at what we did with
WildFly Glow, we have a strong foundation to capture all these data.
The https://github.com/wildfly/wildfly-galleon-feature-packs is a "magical" Git
repository that lists for every version of WildFly the feature packs that we provide.
From there, we should be able to find the layers that are contributed by these feature
packs, the API that they provide and the resources they install. From these resources, we
should be able to end up with something very similar to the model reference with the
description of the resources, their default values, units, the expressions that can be
used to customize them, etc.
Ideally, I would like to end with a web site that tells me:
* WildFly 35.0.1.Final is supporting LangChain4j with its
"org.wildfly:wildfly-ai-galleon-pack" feature pack and its "ai"
layer.
* This galleon pack is incubating and is subject to changes.
* If you want to use Ollama, this galleon pack also provides the ollama-chat-model,
ollama-embedding-model, and ollama-streaming-chat-model
* The ollama-chat-model has a default temperature of 0.9 that can be customized with the
env var ORG_WILDFLY_AI_OLLAMA_CHAT_TEMPERATURE
I'm thinking about creating a WildFly proposal to capture these doc/UX improvements as
they will be relevant to all the feature packs we are delivering (including WildFly
itself) as well as having the tools for user feature packs that are not curated by WildFly
Glow.
Traditionally we have used WildScribe to generate the Model reference that we publish in
our docs but I’m not sure how much can be reused from this top down approach where I want
to know which resources are contributed by which layer & galleon pack.
What do you think?
[1] https://docs.wildfly.org/35/wildscribe/
[2] https://jakarta.ee/specifications/platform/10/apidocs/
[3] https://javadoc.io/doc/org.eclipse.microprofile/microprofile/latest/
[4]
https://github.com/wildfly/wildfly/blob/8302c565354934b3a20f3c06abc4759a5...
--
Jeff Mesnil
Engineer @ Red Hat
http://jmesnil.net/