Docs in asciidoc & deploy antora docs after build

.github/workflows/deploy.yml

@@ -132,8 +132,8 @@ jobs:
           export REPO_NAME_LC=$(echo '${{github.event.repository.name}}' | tr '[:upper:]' '[:lower:]')
           export SITE_DOC_FOLDER=openam-documentation/openam-doc-source
           cd doc.openidentityplatform.org
-          rm -rf ${REPO_NAME_LC}
-          cp -R ../${SITE_DOC_FOLDER}/target/docbkx/bootstrap ../doc.openidentityplatform.org/${REPO_NAME_LC}
+          rm -rf ${REPO_NAME_LC}/modules
+          cp -R ../${SITE_DOC_FOLDER}/target/asciidoc/antora/modules ../doc.openidentityplatform.org/${REPO_NAME_LC}
           git add -A
           git commit -a -m "upload ${{github.event.repository.name}} docs after deploy ${{ github.sha }}"
           git push --force https://github.com/OpenIdentityPlatform/doc.openidentityplatform.org.git

openam-documentation/openam-doc-source/pom.xml

@@ -70,7 +70,10 @@
         <profile>
             <id>man-pages</id>
             <activation>
-                <os><family>unix</family></os>
+                <os>
+                    <family>unix</family>
+                    <name>Linux</name>
+                </os>
                 <jdk>1.8</jdk>
             </activation>
             <build>
@@ -88,6 +91,28 @@
                                     <goal>release</goal>
                                 </goals>
                             </execution>
+                            <execution>
+                                <id>build-man-pages-asciidoc</id>
+                                <phase>package</phase>
+                                <goals>
+                                    <goal>asciidoc-pre-process</goal>
+                                    <goal>antora</goal>
+                                    <goal>asciidoc-to-pdf</goal>
+                                </goals>
+                                <configuration>
+                                    <documents>
+                                        <document>getting-started</document>
+                                        <document>install-guide</document>
+                                        <document>upgrade-guide</document>
+                                        <document>admin-guide</document>
+                                        <document>dev-guide</document>
+                                        <document>deployment-planning</document>
+                                        <document>reference</document>
+                                        <document>web-users-guide</document>
+                                        <document>jee-users-guide</document>
+                                    </documents>
+                                </configuration>
+                            </execution>
                         </executions>
                         <configuration>
                             <projectName>OpenAM</projectName>

openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/appendix-interface-stability.adoc

@@ -0,0 +1,33 @@
+////
+  The contents of this file are subject to the terms of the Common Development and
+  Distribution License (the License). You may not use this file except in compliance with the
+  License.
+
+  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+  specific language governing permission and limitations under the License.
+
+  When distributing Covered Software, include this CDDL Header Notice in each file and include
+  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+  Header, with the fields enclosed by brackets [] replaced by your own identifying
+  information: "Portions copyright [year] [name of copyright owner]".
+
+  Copyright 2017 ForgeRock AS.
+  Portions Copyright 2024 3A Systems LLC.
+////
+
+:figure-caption!:
+:example-caption!:
+:table-caption!:
+
+
+[appendix]
+[#appendix-interface-stability]
+== Release Levels and Interface Stability
+
+This appendix includes Open Identity Platform definitions for product release levels and interface stability.
+
+include::../partials/sec-release-levels.adoc[]
+
+include::../partials/sec-interface-stability.adoc[]
+
+

openam-documentation/openam-doc-source/src/main/asciidoc/admin-guide/chap-admin-tools.adoc

@@ -0,0 +1,174 @@
+////
+  The contents of this file are subject to the terms of the Common Development and
+  Distribution License (the License). You may not use this file except in compliance with the
+  License.
+
+  You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+  specific language governing permission and limitations under the License.
+
+  When distributing Covered Software, include this CDDL Header Notice in each file and include
+  the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+  Header, with the fields enclosed by brackets [] replaced by your own identifying
+  information: "Portions copyright [year] [name of copyright owner]".
+
+  Copyright 2017 ForgeRock AS.
+  Portions Copyright 2024 3A Systems LLC.
+////
+
+:figure-caption!:
+:example-caption!:
+:table-caption!:
+
+
+[#chap-admin-tools]
+== Administration Interfaces and Tools
+
+This chapter provides a brief introduction to the web-based OpenAM console. It also lists and describes each command-line interface (CLI) administration tool.
+
+[#openam-console-overview]
+=== OpenAM Web-Based Console
+
+After you install OpenAM, log in to the web-based console as OpenAM administrator, `amadmin` with the password you set during installation. Navigate to a URL, such as `\http://openam.example.com:8080/openam`. In this case, communications proceed over the HTTP protocol to a FQDN (`openam.example.com`), over a standard Java EE web container port number (8080), to a specific deployment URI (`/openam`).
+
+[#figure-console-as-amadmin]
+image::images/console-as-amadmin.png[]
+When you log in as the OpenAM administrator, `amadmin`, you have access to the complete OpenAM console. In addition, OpenAM has set a cookie in your browser that lasts until the session expires, you logout, or you close your browser.footnote:d19490e334[Persistent cookies can remain valid when you close your browser. This section reflects OpenAM default behavior before you configure additional functionality.]
+
+When you log in to the OpenAM console as a non-administrative end user, you do not have access to the administrative console. Your access is limited to self-service profile pages and user dashboard.
+
+[#figure-console-non-admin-user]
+image::images/console-non-admin-user.png[]
+If you configure OpenAM to grant administrative capabilities to another user, then that user is able to access both the administration console in the realms they can administrate, and their self-service profile pages.
+
+[#figure-console-as-delegated-admin]
+image::images/console-as-delegated-admin.png[]
+For more on delegated administration, see xref:chap-realms.adoc#delegating-realm-administration-privileges["Delegating Realm Administration Privileges"].
+
+[#web-console-responsiveness]
+==== OpenAM Console Responsiveness
+
+The OpenAM web-based console is a responsive website, which means it would resize some of its features to fit the size of your screen and the layout design.
+
+For example, the header menu would change into a dropdown menu, and those pages with many tabs would shed most of them for a dropdown menu to the left-hand side.
+
+[#figure-console-responsiveness-tabs]
+image::images/console-responsiveness.png[]
+
+
+[#web-console-search]
+==== OpenAM Console Search Feature
+
+Use the search box to find any configuration attribute on the section you are in. It can autocomplete the word you are typing, or you can click on the box and display the list of available attributes for you.
+
+[#figure-console-search-feature]
+image::images/console-search.png[]
+
+
+
+[#openam-cli-overview]
+=== OpenAM Command-Line Tools
+
+The script tools in the following list have `.bat` versions for use on Microsoft Windows.
+--
+You can install the following OpenAM command-line tools:
+
+`agentadmin`::
+This tool lets you manage OpenAM policy agent installations.
+
++
+Unpack this tool as part of policy agent installation.
+
+`ampassword`::
+This tool lets you change OpenAM Administrator passwords, and display encrypted password values.
+
++
+Install this from the `SSOAdminTools-13.5.2.zip`.
+
+`amverifyarchive`::
+This tool checks log archives for tampering.
+
++
+Install this from `SSOAdminTools-13.5.2.zip`.
+
+`openam-distribution-configurator-13.5.2.jar`::
+This executable `.jar` file lets you perform a silent installation of an OpenAM server with a configuration file. For example, the `java -jar configurator.jar -f config.file` command couples the `configurator.jar` archive with the __config.file__. The `sampleconfiguration` file provided with the tool is set up with the format for the `config.file`, and it must be adapted for your environment.
+
++
+Install this from `SSOConfiguratorTools-13.5.2.zip`.
+
+`ssoadm`::
+This tool provides a rich command-line interface for the configuration of OpenAM core services.
+
++
+In a test environment, you can activate `ssoadm.jsp` to access the same functionality in your browser. Once active, you can use many features of the `ssoadm` command by navigating to the `ssoadm.jsp` URI, in a URL, such as `\http://openam.example.com:8080/openam/ssoadm.jsp`.
+
++
+Install this from `SSOAdminTools-13.5.2.zip`.
+
++
+To translate settings applied in OpenAM console to service attributes for use with `ssoadm`, log in to the OpenAM console as `amadmin` and access the services page, in a URL, such as `\http://openam.example.com:8080/openam/services.jsp`.
+
+--
+The commands access the OpenAM configuration over HTTP (or HTTPS). When using the administration commands in a site configuration, the commands access the configuration through the front end load balancer.
+Sometimes a command cannot access the load balancer because:
+
+* Network routing restrictions prevent the tool from accessing the load balancer.
+
+* For testing purposes, the load balancer uses a self-signed certificate for HTTPS, and the tool does not have a way of trusting the self-signed certificate.
+
+* The load balancer is temporarily unavailable.
+
+In such cases you can work around the problem by adding an option for each node, such as the following to the `java` command in the tool's script.
+
+Node 1:
+
+[source]
+----
+-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=
+   http://server1.example.com:8080/openam"
+----
+Node 2:
+
+[source]
+----
+-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=
+   http://server2.example.com:8080/openam"
+----
+In the above example the load balancer is on the `lb` host, `\https://lb.example.com:443/openam` is the site name, and the OpenAM servers in the site are on `server1` and `server2`.
+
+The `ssoadm` command will only use the latest value in the map, so if you have a mapping like:
+
+[source]
+----
+-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=
+   http://server1.example.com:8080/openam, https://lb.example.com:443/openam=
+   http://server2.example.com:8080/openam"
+----
+The `ssoadm` command will always talk to:
+
+[source]
+----
+http://server2.example.com:8080/openam
+----
+
+
+[#openam-ssoadm-jsp-overview]
+=== OpenAM ssoadm.jsp
+
+You can use the `ssoadm.jsp` page to access a large subset of the configuration capabilities of the `ssoadm` command. Yet, `ssoadm.jsp` is disabled by default to prevent potential misuse.
+
+[#enable-ssoadm-jsp]
+.To Enable ssoadm.jsp
+====
+
+. Log in as OpenAM administrator, `amadmin`.
+
+. Navigate to Deployment > Servers > __Server Name__ > Advanced.
+
+. Add a new advanced property called `ssoadm.disabled` with the value of `false`.
+
+. To see if the change worked, navigate to the URL of OpenAM with the `/ssoadm.jsp` URI. For example, navigate to `\http://openam.example.com:8080/openam/ssoadm.jsp`.
+
+====
+
+