Further doc changes

Bedework · Oct 4, 2024 · 3846bd0 · 3846bd0
1 parent bd19ba1
commit 3846bd0
Show file tree

Hide file tree

Showing 7 changed files with 349 additions and 362 deletions.
diff --git a/docs/index.html b/docs/index.html
diff --git a/src/main/asciidoc/deployers/databases.adoc b/src/main/asciidoc/deployers/databases.adoc
@@ -1,8 +1,8 @@
-[setting-up-databases]
+[[setting-up-databases]]
 === Setting up databases
 The quickstart is configured to use h2 for demonstration only. For production, you will need to switch to something like postgresql or mysql.
 
-Below there is some help on configuring th edatabase. Additionally, there is some information on reconfiguring wildfly. A better approach is to install a configuration specifically for the desired database using galleon. In that case any information on wildfly configuration can be skipped.
+Below there is some help on configuring the database. Additionally, there is some information on reconfiguring wildfly. A better approach is to install a configuration specifically for the desired database using galleon. In that case any information on wildfly configuration can be skipped.
 
 ==== postgresql
 We'll describe the process for the main calendar engine. The others are very similar.
@@ -48,123 +48,56 @@ The psql commands are something like:
 
 [source]
 ----
-create role bedework with login password 'xxxxxxxxx';
-create database caldb owner bedework;
+create role bw with login password 'xxxxxxxxx';
+create database caldb owner bw;
 ----
 
 Some or all of the following seems to be required. Note it also seems to be important to connect to the database first:
 ----
 \c caldb
-GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO bedework;
-grant all privileges on database caldb to bedework;
+GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO bw;
+grant all privileges on database caldb to bw;
 ----
 
-Set the hibernate dialect in the config file:
-[source,xml]
-----
-    <hibernateProperty>hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect</hibernateProperty>
-----
-
-In standalone.xml replace the datasource definition with something like:
+===== Check configurations
+You MUST install the postgres version for this to work. Most of the configuration is already done for you. You will need to provide the id and password.
 
-[source,xml]
+Configuration overrides are found in
 ----
-    <datasource jta="true" jndi-name="java:/CalendarDS" pool-name="CalendarDS" enabled="true" use-ccm="false">
-       <connection-url>jdbc:postgresql://localhost:5432/caldb</connection-url>
-       <driver>postgresql</driver>
-       <pool>
-         <min-pool-size>1</min-pool-size>
-         <max-pool-size>50</max-pool-size>
-         <prefill>true</prefill>
-      </pool>
-       <security>
-         <user-name>xxxxx</user-name>
-         <password>xxxxx</password>
-       </security>
-       <timeout>
-        <idle-timeout-minutes>15</idle-timeout-minutes>
-       </timeout>
-        <validation>
-          <validate-on-match>true</validate-on-match>
-          <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"></valid-connection-checker>
-
-          <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"></exception-sorter>
-       </validation>
-       <statement>
-         <share-prepared-statements>false</share-prepared-statements>
-       </statement>
-     </datasource>
-----
-
-Ensure you also have the driver loaded - for example the drivers section which usually follows the datasources shoudllook somethign like:
-
-You need to install the postgres driver - you're either missing the driver declaration - something like:
-
-[source,xml]
-----
-<drivers>
-    ...
-    <driver name="postgresql" module="org.postgresql"/>
-    ...
-</drivers>
+<wildfly>/bin/bwcommon.conf
 ----
 
-Ensure the jdbc driver is installed in the modules directory - something like:
-
-[source]
+For example: replace
 ----
-wildfly/modules/org/postgresql/main/module.xml
-wildfly/modules/org/postgresql/main/postgresql-8.4-701.jdbc4.jar
+#JAVA_OPTS="$JAVA_OPTS -Dorg.bedework.site.db.id.calendar=sa
+#JAVA_OPTS="$JAVA_OPTS -Dorg.bedework.site.db.pw.calendar=sa
 ----
 
-Module.xml for this example contains
+with
 
-[source,xml]
 ----
-<?xml version='1.0' encoding='UTF-8'?>
-
-<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
-    <resources>
-        <resource-root path="postgresql-8.4-701.jdbc4.jar"/>
-    </resources>
-
-    <dependencies>
-        <module name="javax.api"/>
-        <module name="javax.transaction.api"/>
-    </dependencies>
-</module>
+JAVA_OPTS="$JAVA_OPTS -Dorg.bedework.site.db.id.calendar=bw
+#JAVA_OPTS="$JAVA_OPTS -Dorg.bedework.site.db.pw.calendar=xxxx
 ----
 
-Modify it appropriately for different versions.
-
-Start wildfly and allow it to fully deploy. There will be many errors relating to the calendar database.
-
-Delete the file ***wildfly/standalone/data/bedework/dumprestore/schema.sql***
-
-===== Use the cli to install the schema.
-
-To run the cli you need the id and password you created when configuring wildfly. This id and password can also be used to access the hawtio console.
+Use the psql client application to install the initial schema and data.
 
 [source]
 ----
-cd bw-cli/target/client/bin
-./client -id admin-id -pw admin-pw
-calschema export
+psql caldb < <path-to-wildfly>/standalone/data/bedework/postgresql/caldb.sql
 ----
 
-This should install the schema. It will also create a file which can be manually installed if need be - use the psql client application
-
-[source]
-----
-psql caldb < wildfly/standalone/data/bedework/dumprestore/schema.sql
-----
+Note this file sets the owner to 'bw'. If you want a different owner then edit the file first.
 
-Next you need to add some basic data. For this you need the full path to the initial data in wildfly/standalone/data/bedework/dumprestore/initbedework.xml
+===== Install opensearch
+===== Start wildfly
+There will be a number of erros because of the lack of data
 
 In the cli enter the command
 
 [source]
 ----
+./wildfly/bin/bwcli.sh jmxUrl http://localhost:8080/jolokia -id <id> -pw <pw>
 restoreCal "/full/path/to/initbedework.xml"
 ----
 The quotes are required. Some activity should ensue.

diff --git a/src/main/asciidoc/deployers/featurepack-install.adoc b/src/main/asciidoc/deployers/featurepack-install.adoc
@@ -50,13 +50,25 @@ wget https://github.com/wildfly/galleon/releases/download/5.2.2.Final/galleon-5.
 ----
 and unzip.
 
-* run galleon to install - this is all one command:
+* run galleon to install:
 ----
-./galleon-5.2.2.Final/bin/galleon.sh \
-   install org.bedework.deploy:bw-wf-feature-pack:4.1.0
+./galleon-5.2.2.Final/bin/galleon.sh
+----
+The first time, if you want to install snapshot versions, you need to set up repositories and resolve for the required version
+----
+maven add-repository --name=ossrh --url=https://oss.sonatype.org/content/repositories/snapshots/ --enable-snapshot=true
+maven resolve-feature-pack org.bedework.deploy:bw-wf-feature-pack:4.1.1-SNAPSHOT
+----
+then install
+----
+install org.bedework.deploy:bw-wf-feature-pack:4.1.0
    --dir=wildfly --verbose --layers=bw-demoall-h2,web-console
 ----
 
+Finally
+----
+exit
+----
 * In window 2 cd into the same directory and start the required services:
 ----
     export JAVA_HOME=<where the jdk is installed>

diff --git a/src/main/asciidoc/deployers/installing.adoc b/src/main/asciidoc/deployers/installing.adoc
@@ -13,73 +13,12 @@ sudo update-alternatives --config java
 .................
 +
 The last command should state there are no alternatives but if another has been installed pick the appropriate version.
+
 . Install wildfly with bedework using galleon
 +
 If you are not wanting to install the quickstart for builds and development then install a wildfly service by following the instructions at <<featurepack-install>>.
 and disregard the remaining instructions below.
-. Install maven if you want to do builds.
-+
-.................
-sudo apt install maven
-.................
-. Install git if you want to install the quickstart
-+
-.................
-sudo apt install git
-.................
-. Set up maven
-+
-If you are doing builds of versions before 4.0.0 then set up the maven profile which must be named "bedework-3"
-+
-.................
-mkdir ~/.m2
-emacs ~/.m2/settings.xml
-.................
-+
-and paste in a modified form of the following (change the paths
-"/home/mike/bedework/" to correspond to the directory you're about
-to create)
-+
-.................
-<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
-xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
-                         http://maven.apache.org/xsd/settings-1.0.0.xsd">
-<pluginGroups>
-<pluginGroup>org.bedework</pluginGroup>
-</pluginGroups>
-
-  <profiles>
-    <profile>
-      <id>bedework-3</id>
-      <activation>
-        <activeByDefault>true</activeByDefault>
-      </activation>
-      <properties>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
-        <org.bedework.deployment.basedir>/home/mike/bedework/quickstart-dev</org.bedework.deployment.basedir>
-        <org.bedework.deployment.properties>/home/mike/bedework/quickstart-dev/bedework/config/wildfly.deploy.properties</org.bedework.deployment.properties>
-      </properties>
-    </profile>
-  </profiles>
-</settings>
-.................
-. Provide a bw settings file.
-+
-If necessary create a *.bw* file in your home directory and add properties to it. Currently, the only properties allow setting the profile for the *.bw* script used to build and the location of the deployment proeprties used to configure your deployed modules.
-+
-An example file is
-+
-.................
-#
-# Defaults for bw script
-#
-echo "Setting defaults from .bw"
-bw_mvnProfile="-P bedework_dev"
 
-bw_deployProps="/home/myhome/bwstuff/myprops.properties"
-.................
 . Install the quickstart
 +
 We create a directory in which to install bedework, download an install script and execute the script.
@@ -98,7 +37,7 @@ Some time will pass. You'll be asked to provide an id and password for wildfly a
 
 . Install OpenSearch 1.2.3
 +
-The eployed wildfly has scripts to install a docker image and start and stop it. See <<opensearch>> for instructions on installing and (re)indexing.
+The deployed wildfly has scripts to install a docker image and start and stop it. See <<installing-opensearch>> for instructions on installing and (re)indexing.
 You'll need to start the system before reindexing.
 
 . Start the system

diff --git a/src/main/asciidoc/deployers/opensearch.adoc b/src/main/asciidoc/deployers/opensearch.adoc
@@ -1,5 +1,5 @@
-[[opensearch, Install and configure OpenSearch]]
-=== OpenSearch
+[[installing-opensearch]]
+=== Install and configure OpenSearch
 Bedework uses OpenSearch as the indexer engine. As objects are created destroyed and updated they are indexed through calls to the indexer. The indexer can run as a local application, useful for development - or as an external service - which will be required for clustering.
 
 It is safer to NOT run in production with the OpenSearch interfaces open to the outside. OpenSearch now has various configuration options available. Bedework supports basic user authentication. Currently, you can run unauthenticated but OpenSearch will generate a lot of warnings in the log.

diff --git a/src/main/asciidoc/development/building.adoc b/src/main/asciidoc/development/building.adoc
@@ -0,0 +1,92 @@
+[[building-bedwork]]
+=== Building bedework
+
+Any examples tend to be ubuntu but bedework can be built on any system that supports java17.
+
+. Ensure java 17 jdk is installed
++
+.................
+sudo apt-get install openjdk-17-jdk-headless
+sudo update-alternatives --config java
+.................
++
+The last command should state there are no alternatives but if another has been installed pick the appropriate version.
+
+. Install maven
+.................
+sudo apt install maven
+.................
+
+. Install git
++
+.................
+sudo apt install git
+.................
+
+. Set up maven
++
+If you are doing builds of versions before 4.0.0 then set up the maven profile which must be named "bedework-3"
++
+.................
+mkdir ~/.m2
+emacs ~/.m2/settings.xml
+.................
++
+and paste in a modified form of the following (change the paths
+"/home/mike/bedework/" to correspond to the directory you're about
+to create)
++
+.................
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+                         http://maven.apache.org/xsd/settings-1.0.0.xsd">
+<pluginGroups>
+<pluginGroup>org.bedework</pluginGroup>
+</pluginGroups>
+
+  <profiles>
+    <profile>
+      <id>bedework-3</id>
+      <activation>
+        <activeByDefault>true</activeByDefault>
+      </activation>
+      <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <org.bedework.deployment.basedir>/home/mike/bedework/quickstart-dev</org.bedework.deployment.basedir>
+        <org.bedework.deployment.properties>/home/mike/bedework/quickstart-dev/bedework/config/wildfly.deploy.properties</org.bedework.deployment.properties>
+      </properties>
+    </profile>
+  </profiles>
+</settings>
+.................
+. Provide a bw settings file.
++
+If necessary create a *.bw* file in your home directory and add properties to it. Currently, the only properties allow setting the profile for the *.bw* script used to build and the location of the deployment proeprties used to configure your deployed modules.
++
+An example file is
++
+.................
+#
+# Defaults for bw script
+#
+echo "Setting defaults from .bw"
+bw_mvnProfile="-P bedework_dev"
+
+bw_deployProps="/home/myhome/bwstuff/myprops.properties"
+.................
+
+. Create a directory in which to place sources and wildfly.
++
+Much of the build assumes a directory in which we have each of the bedework projects and a working wildfly deployment. We'll refer to this directory as <bw>.
+
+. Cd into <bw> and install wildfly
++
+Follow the instructions in <<installing-bedwork>>. Choose a version which runs your db of choice and installs a copy of opensearch.
++
+If you want to use postgres as your db you need to install that yourself. See <<setting-up-databases>>
+
+. Create wildfly symlink
++
+This provides a consistent name for the server.
diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc
@@ -62,6 +62,7 @@ include::{deployer-dir}locations.adoc[]
 include::{dev-dir}todo.adoc[]
 include::{dev-dir}debugging.adoc[]
 include::{dev-dir}caldavtester.adoc[]
+include::{dev-dir}building.adoc[]
 
 [[older-releases]]
 == Older Bedework Versions (3.10 and Prior)