Initial documentation #153
Conversation
dist/docs/guide/channels/index.adoc
Outdated
| ## Working with channels | ||
|
|
||
| More information on the wildfly channels can be found in https://github.com/wildfly-extras/wildfly-channel/blob/main/doc/spec.adoc. This chapter is intended to explain some concepts behind different channel types and how they can be used to provide software updates. | ||
|
|
||
| ### "Open" channels |
There was a problem hiding this comment.
I would add a simple channel type listing after the first paragraph, to establish what the channel types are called, before diving into the chapters describing each type.
... This chapter is intended to explain some concepts behind different channel types...
The two supported channel types are:
- open channel,
- manifest channel.
[And the two chapters follow...]
There was a problem hiding this comment.
A tentative suggestion: Maybe we should make the "manifest channel" more prominent, by describing it first and maybe noting that open channels are intended for development purposes and typically manifest channels are used, or something like that.
As we don't expect typical user to use open channels...
There was a problem hiding this comment.
Or even more tentative: maybe we should not distinguish the channel types at all? As it's not really a type of a channel but a type of a stream. Channel can contain mix of "specific versions" streams and "version pattern" streams, it's not like it's exclusive.
That would allow to simplify docs a bit. We would just add footnotes that "btw instead of specifying specific version you can also set a versionPattern and if you don't want to list all your artifacts in a manifest you can set resolve-if-no-stream: latest. But the officially released channels don't use these features."
There was a problem hiding this comment.
That's good point. Open/manifest channels is more a conceptual thing then an actual channel type. I reworked that section trying to explain it a bit more, WDYT?
| @@ -1,31 +1,7 @@ | |||
| ### Promoting custom artifacts | |||
|
|
|||
| To make the changes available to the servers, they need to be made available in a custom channel. This process is called *promoting artifacts*. Promoted artifacts can come from a different channel (eg. promoting artifacts between STAGE and PROD channels) or from an artifact bundle. | |||
| To make the custom artifact available to registered servers, the content of `maven-repository` customization should be placed at the root of customization repository folder. | |||
There was a problem hiding this comment.
This is bit difficult to imagine, I'm not sure what "customization repository folder" is. Maybe it would deserve a diagram.
There was a problem hiding this comment.
I expanded the description and added a command line example. Does that make it a bit clearer?
dist/docs/guide/usage/install.adoc
Outdated
| ### Installation | ||
|
|
||
| To provision a Wildfly server, Prospero requires following information: | ||
|
|
||
| * manifest definition | ||
| * location of channel's Maven repositories | ||
| * feature-pack name | ||
|
|
There was a problem hiding this comment.
We should maybe state that there are three possible inputs for the installation: 1. predefined profile; 2. fpl; 3. galleon provisioning.xml file, and give examples for each of those. It would then come up naturally that provisioning.xml allows for customizations.
Now in the "Customizing server installation" section bellow the provisioning.xml file comes bit out of the blue.
There was a problem hiding this comment.
Good point. I think I'm going to create 3 sub-sections describing each of the different options:
- Installing predefined server profile
- Installing a feature pack
- Installing a customized feature pack
dist/docs/guide/channels/index.adoc
Outdated
|
|
||
| This type of channel can be useful when the content of repositories can be controlled and trusted. Any new artifact deployed into the channel repository, will automatically be made available for subscribed servers. | ||
| * using an artifact manifest with fixed versions, or | ||
| * rely on Maven metadata. |
There was a problem hiding this comment.
The "Maven metadata" seems a bit abstract. Can it be called "using regular expression version pattern" or something similar instead?
There was a problem hiding this comment.
Or "dynamic version patterns"?
There was a problem hiding this comment.
The maven-metadata.xml is what ultimately dictates the version when either regular expressions or resolve-if-no-latest is used. The regular expressions are just used to filter subset of the available versions.
Is one of this better "use versions from maven-metadata.xml in underlying repositories" or "use versions provided by underlying Maven repositories"?
There was a problem hiding this comment.
I wouldn't mention "maven metadata" because that's implementation detail of maven repositories. If maven repo is in consistent state the metadata files should be sorted out.
What about "use the latest artifact version available in backing Maven repository", eventually expand of version patterns in separate paragraph?
| @@ -1,6 +1,33 @@ | |||
| ### Promoting custom artifacts | |||
There was a problem hiding this comment.
When is this operation needed? If I have "customization bundle" (zip), I can apply it as such, without having custom repository?
But I won't be able to use rollback operation in future, unless I have the customization bundle artifacts copied to custom repo?
There was a problem hiding this comment.
Currently the customization bundle is just a mechanism for distributing changes. It's not directly consumed by prospero, it has to be extracted and the server needs to be subscribed to it. In a simple case the extracted content of the bundle basically become the customization repository.
The idea of promoting artifacts is about updating that repository when new version of customization bundle is available.
|
|
||
| Prospero delegates provisioning server to Galleon. When Galleon attempts to resolve components needed by the server, instead of using versions provided by the feature packs, Prospero intercepts that request and uses Wildfly Channels to find the correct version of the component and resolve it from the channels repositories. | ||
|
|
||
| image::overview.png[] |
There was a problem hiding this comment.
TODO - missing picture.
There was a problem hiding this comment.
sorry, it slipped the commit, pushed now
No description provided.