ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
= Embedded Web Server
:idprefix:
:idseparator: -
Apache ActiveMQ Artemis embeds the https://www.eclipse.org/jetty/[Jetty web server].
Its main purpose is to host the xref:management-console.adoc#management-console[Management Console].
However, it can also host other web applications.
== Configuration
The embedded Jetty instance is configured in `etc/bootstrap.xml` via the `web` element, e.g.:
[,xml]
----
<web path="web">
<binding uri="http://localhost:8161">
<app url="activemq-branding" war="activemq-branding.war"/>
<app url="artemis-plugin" war="artemis-plugin.war"/>
<app url="console" war="console.war"/>
</binding>
</web>
----
=== Web
The `web` element has the following attributes:
path::
The name of the subdirectory in which to find the web application archives (i.e. WAR files).
This is a subdirectory of the broker's home or instance directory.
customizer::
The name of customizer class to load.
rootRedirectLocation::
The location to redirect the requests with the root target.
webContentEnabled::
Whether or not the content included in the web folder of the home and the instance directories is accessible.
Default is `false`.
2023-11-28 13:52:30 -05:00
maxThreads::
The maximum number of threads the embedded web server can create to service HTTP requests.
Default is `200`.
minThreads::
The minimum number of threads the embedded web server will hold to service HTTP requests.
Default is `8` or the value of `maxThreads` if it is lower.
idleThreadTimeout::
The time to wait before terminating an idle thread from the embedded web server. Measured in milliseconds. Default is `60000`.
2024-01-28 07:40:14 -05:00
scanPeriod::
How often to scan for changes of the key and trust store files related to a binding when the `sslAutoReload` attribute value of the `binding` element is `true`, for further details see <<Binding>>. Measured in seconds. Default is `5`.
2024-07-19 13:45:50 -04:00
maxRequestHeaderSize::
The maximum allowed size for the HTTP request line and HTTP request headers.
Measured in bytes.
Default is `8192`.
maxResponseHeaderSize::
The maximum allowed size for the HTTP response headers.
Measured in bytes.
Default is `8192`.
ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
=== Binding
The `web` element should contain at least one `binding` element to configure how clients can connect to the web-server.
A `binding` element has the following attributes:
uri::
The protocol to use (i.e. `http` or `https`) as well as the host and port on which to listen.
This attribute is required.
clientAuth::
Whether or not clients should present an SSL certificate when they connect.
Only applicable when using `https`.
passwordCodec::
The custom coded to use for unmasking the `keystorePassword` and `trustStorePassword`.
keyStorePath::
The location on disk of the keystore.
Only applicable when using `https`.
keyStorePassword::
The password to the keystore.
Only applicable when using `https`.
Can be masked using `ENC()` syntax or by defining `passwordCodec`.
See more in the xref:masking-passwords.adoc#masking-passwords[password masking] chapter.
trustStorePath::
The location on disk for the truststore.
Only applicable when using `https`.
trustStorePassword::
The password to the truststore.
Only applicable when using `https`.
Can be masked using `ENC()` syntax or by defining `passwordCodec`.
See more in the xref:masking-passwords.adoc#masking-passwords[password masking] chapter.
includedTLSProtocols::
A comma seperated list of included TLS protocols, ie `"TLSv1,TLSv1.1,TLSv1.2"`.
Only applicable when using `https`.
excludedTLSProtocols::
A comma seperated list of excluded TLS protocols, ie `"TLSv1,TLSv1.1,TLSv1.2"`.
Only applicable when using `https`.
includedCipherSuites::
A comma seperated list of included cipher suites.
Only applicable when using `https`.
excludedCipherSuites::
A comma seperated list of excluded cipher suites.
Only applicable when using `https`.
sniHostCheck::
Whether or not the SNI Host name in the client request must match the common name or the subject alternative names in the server certificate.
Default is `true`.
Only applicable when using `https`.
sniRequired::
Whether or not the client request must include an SNI Host name.
Default is `false`.
Only applicable when using `https`.
2024-01-28 07:40:14 -05:00
sslAutoReload::
Whether or not the key and trust store files must be watched for changes and automatically reloaded.
The watch period is controlled by the `scanPeriod` attribute of the `web` element, for further details see <<Web>>.
Default is `false`.
ARTEMIS-4383 migrate user docs to AsciiDoc
Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
2023-07-27 23:45:17 -04:00
=== App
Each web application should be defined in an `app` element inside an `binding` element.
The `app` element has the following attributes:
url::
The context to use for the web application.
war::
The name of the web application archive on disk.
== Request Log
It's also possible to configure HTTP/S request logging via the `request-log` element which has the following attributes:
filename::
The full path of the request log.
This attribute is required.
append::
Whether or not to append to the existing log or truncate it.
Boolean flag.
extended::
Whether or not to use the extended request log format.
Boolean flag.
If `true` will use the format `+%{client}a - %u %t "%r" %s %O "%{Referer}i" "%{User-Agent}i"+`.
If `false` will use the format `+%{client}a - %u %t "%r" %s %O+`.
Default is `false`.
See the https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html[format specification] for more details.
filenameDateFormat::
The log file name date format.
retainDays::
The number of days before rotated log files are deleted.
ignorePaths::
Request paths that will not be logged.
Comma delimited list.
format::
Custom format to use.
If set this will override `extended`.
See the https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html[format specification] for more details.
The following options were previously supported, but they were replaced by the `format`: `logCookie`, `logTimeZone`, `logDateFormat`, `logLocale`, `logLatency`, `logServer`, `preferProxiedForAddress`.
All these options are now deprecated and ignored.
These attributes are essentially passed straight through to the underlying https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/CustomRequestLog.html[`org.eclipse.jetty.server.CustomRequestLog`] and https://www.eclipse.org/jetty/javadoc/jetty-9/org/eclipse/jetty/server/RequestLogWriter.html[`org.eclipse.jetty.server.RequestLogWriter`] instances.
Default values are based on these implementations.
Here is an example configuration:
[,xml]
----
<web path="web">
<binding uri="http://localhost:8161">
<app url="activemq-branding" war="activemq-branding.war"/>
<app url="artemis-plugin" war="artemis-plugin.war"/>
<app url="console" war="console.war"/>
</binding>
<request-log filename="${artemis.instance}/log/http-access-yyyy_MM_dd.log" append="true" extended="true"/>
</web>
----
=== System properties
It is possible to use system properties to add or update web configuration items.
If you define a system property starting with "webconfig." it will be parsed at the startup to update the web configuration.
To enable the client authentication for an existing binding with the name `artemis`, set the system property `webconfig.bindings.artemis.clientAuth` to `true`, i.e.
----
java -Dwebconfig.bindings.artemis.clientAuth=true
----
To add a new binding or app set the new binding or app attributes using their new names, i.e.
----
java -Dwebconfig.bindings.my-binding.uri=http://localhost:8162
java -Dwebconfig.bindings.my-binding.apps.my-app.uri=my-app
java -Dwebconfig.bindings.my-binding.apps.my-app.war=my-app.war
----
To update a binding without a name use its uri and to update an app without a name use its url , i.e.
[,xml]
----
<web path="web">
<binding uri="http://localhost:8161">
<app url="activemq-branding" war="activemq-branding.war"/>
...
----
----
java -Dwebconfig.bindings."http://localhost:8161".clientAuth=true
----
----
java -Dwebconfig.bindings."http://localhost:8161".apps."activemq-branding".war=my-branding.war
----
== Proxy Forwarding
The proxies and load balancers usually support `X-Forwarded` headers to send information altered or lost when a proxy is involved in the path of the request.
Jetty supports the https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] customizer to handle `X-Forwarded` headers.
Set the `customizer` attribute via the `web` element to enable the https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] customizer, ie:
[,xml]
----
<web path="web" customizer="org.eclipse.jetty.server.ForwardedRequestCustomizer">
<binding uri="http://localhost:8161">
<app url="activemq-branding" war="activemq-branding.war"/>
<app url="artemis-plugin" war="artemis-plugin.war"/>
<app url="console" war="console.war"/>
</binding>
</web>
----
== Management
The embedded web server can be stopped, started, or restarted via any available management interface via the `stopEmbeddedWebServer`, `starteEmbeddedWebServer`, and `restartEmbeddedWebServer` operations on the `ActiveMQServerControl` respectively.
