Development

software/core/oqm-core-api/build.gradle

@@ -8,7 +8,7 @@ plugins {
 }
 
 group 'com.ebp.openQuarterMaster'
-version '5.0.0'
+version '6.0.0-SNAPSHOT'
 
 repositories {
 	mavenCentral()
@@ -39,7 +39,7 @@ dependencies {
 	implementation 'org.jboss.slf4j:slf4j-jboss-logmanager'
 
 	implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
-	implementation "com.fasterxml.jackson.datatype:jackson-datatype-javax-money:2.21.3"
+	implementation "com.fasterxml.jackson.datatype:jackson-datatype-javax-money:2.22.0"
 	implementation 'com.fasterxml.jackson.module:jackson-module-blackbird'
 
 	// https://mvnrepository.com/artifact/tech.units/indriya
@@ -53,8 +53,8 @@ dependencies {
 	implementation 'org.apache.commons:commons-compress:1.28.0'
 	implementation 'org.apache.commons:commons-io:1.3.2'
 	implementation("commons-validator:commons-validator:1.10.1")
-	implementation 'org.apache.tika:tika-core:3.3.0'
-	implementation 'uk.org.okapibarcode:okapibarcode:0.5.5'
+	implementation 'org.apache.tika:tika-core:3.3.1'
+	implementation 'uk.org.okapibarcode:okapibarcode:0.5.6'
 
 	implementation("org.javamoney:moneta:1.4.5")
 

software/core/oqm-core-api/docs/sphinx-test/source/conf.py

@@ -36,11 +36,14 @@
 	'github_repo': 'OpenQuarterMaster',
 	'github_banner': True,
 	"github_button": False,
-	"show_relbars": True
+	"show_relbars": True,
 	# 'github_count': True,
 	# 'extra_nav_links': {
 	# 	'Index': 'genindex.html',
 	# }
+
+	'body_max_width': 'none',
+	'page_width': '90%',
 }
 html_sidebars = {
 	'**': [

software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst

@@ -10,30 +10,60 @@ Operational / Architecture Decisions
 This section talks to how we arrived at the decisions surrounding how we have built the service, and
 why we chose the tools we did.
 
-Quarkus
--------
+Quarkus / Java
+--------------
+
+`Quarkus <https://quarkus.io>`_ is a fully featured, lean, and performant framework for building many things, but most notably web, container-native services.
+
+Quarkus is Java-based, and thus is the language we are working in. Java was chosen as is a good choice for such services, being a strongly typed language with a mature
+framework ecosystem.
+
+Other options could include Spring, or things in other
 
 Container Deployment
 --------------------
 
+`Containers <https://www.docker.com/resources/what-container/>`_ provide an extreme level of flexibility and ease of deployment in a variety of environments.
+
+If it can run Podman/ Docker, it can run the core API.
+
 MongoDB
 -------
 
+`MongoDB <https://www.mongodb.com/>`_ Is a highly flexible and scalable database. We chose this over \*.sql to leverage:
+
+ * flexibility in data model; can directly use polymorphic objects within the same collection
+ * scalability; naturally a clustered system, can grow with OQM as a cluster
+
 JWT Auth
 --------
 
+`JWTs <https://www.jwt.io/introduction#what-is-json-web-token>`_ are a flexible, implementation independent method for authorization. Being a widely
+used web standard, was a natural choice
+
 Kafka Messaging
 ---------------
 
+`Apache Kafka <https://kafka.apache.org/>`_ is a widely used and supported messaging platform. What made it stand out was a relative level of simplicity,
+both in usage and in deployment.
+
 Optionality
 ^^^^^^^^^^^
 
+It is important to the project to be flexible and modular, and Kafka frankly eats up a lot of computing resources. By making the Core API only optionally
+include connection to a Kafka server, we can omit that overhead when we don't need to include it when the downstream functionality is unused.
+
 OpenTelemetry
 -------------
 
+`OpenTelemetry <https://opentelemetry.io/>`_ is a widely used standard for transferring metrics, logs, and tracing information to tools that can use that information.
+It made sense to adopt, as is largely vendor agnostic.
+
 Optionality
 ^^^^^^^^^^^
 
+As with Kafka, if users don't want the overhead of a metrics stack, the should not need to provide and use one.
+
 Functional / Design Decisions (major)
 =====================================
 

software/core/oqm-core-api/docs/sphinx-test/source/running/03_configuration.rst

@@ -0,0 +1,235 @@
+Configuration Reference
+#######################
+
+Below is the configuration reference to configure your Core API instance.
+
+All values are optional, unless otherwise marked by: *Required*
+
+Core API Specific Configuration
+===============================
+
+.. list-table::
+   :header-rows: 1
+
+   * - Config Key
+     - Description
+     - Values (Examples)
+     - Default
+   * - .. code-block:: none
+
+          service.ops.currency
+     - Sets the currency to be used by the system. Use any value that can be passed to
+       `Currency.getInstance() <https://docs.oracle.com/javase/8/docs/api/java/util/Currency.html#getInstance-java.lang.String->`_
+     - .. code-block:: none
+
+          USD
+       .. code-block:: none
+
+          GBP
+     - .. code-block:: none
+
+                 USD
+   * - .. code-block:: none
+
+          service.item.expiryCheck.cron
+     - Sets the interval at which expiry checks happen. In a cron format. `Docs <https://quarkus.io/guides/scheduler-reference#cron>`_
+     -  .. code-block:: none
+
+           0 0 * ? * * # Every Hour
+     -  .. code-block:: none
+
+           0 0 * ? * * # Every Hour
+   * - .. code-block:: none
+
+          service.tempDir
+     - The directory to be used for temporary file creation and storage. Used for
+     -  .. code-block:: none
+
+           /tmp
+     -  .. code-block:: none
+
+           /tmp/oqm-core-api
+   * - .. code-block:: none
+
+          service.image.resizing.enabled
+     - If the service is to resize images when they are uploaded (images for attached images, not images uploaded as generic files)
+     -  .. code-block:: none
+
+           true
+        .. code-block:: none
+
+           false
+     -  .. code-block:: none
+
+           true
+   * - .. code-block:: none
+
+          service.image.resizing.height
+     - The height to resize images to, in number of pixels.
+     -  .. code-block:: none
+
+           500
+     -  .. code-block:: none
+
+           750
+   * - .. code-block:: none
+
+          service.image.resizing.width
+     - The width to resize images to, in number of pixels.
+     -  .. code-block:: none
+
+           500
+     -  .. code-block:: none
+
+           ${service.image.resizing.height}
+   * - .. code-block:: none
+
+          service.image.resizing.savedType
+     - The image format to use to save the resulting images as.
+     -  Either:
+
+        .. code-block:: none
+
+           jpg
+
+        or:
+
+        .. code-block:: none
+
+           png
+     -  .. code-block:: none
+
+           jpg
+
+MongoDB Configuration
+=====================
+
+For Mongo configuration, we leverage the settings as presented by Quarkus. For convenience, we have the most important configuration below, but
+further options can be found on the `Quarkus MongoDB Configuration <https://quarkus.io/guides/mongodb#configuration-reference>`_ documentation.
+
+Please see :doc:`04_mongo` for more information on how MongoDB is leveraged and used by the Core API.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Config Key
+     - Description
+     - Values (Examples)
+     - Default
+   * - .. code-block:: none
+
+          QUARKUS_MONGODB_CONNECTION-STRING
+
+       *Required*
+     - The connection string to actually connect to Mongo
+     - .. code-block:: none
+
+           mongodb://${user}:${pass}@${host}:${port}
+     - None, must supply this value.
+   * - .. code-block:: none
+
+          QUARKUS_MONGODB_DATABASE
+     - The database to use for OQM. Also the prefix to use for specific datasets.
+     - .. code-block:: none
+
+           openQuarterMaster
+     - .. code-block:: none
+
+          openQuarterMaster
+
+Kafka Configuration
+=====================
+
+For Kafka configuration, we leverage the settings as presented by Quarkus. For convenience, we have the most important configuration below, but
+further options can be found on the `Quarkus Kafka Configuration <https://quarkus.io/guides/kafka#kafka-configuration>`_ documentation.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Config Key
+     - Description
+     - Values (Examples)
+     - Default
+   * - .. code-block:: none
+
+          mp.messaging.outgoing.events-outgoing.enabled
+
+       *Required*
+     - Whether or not to enable the messaging functionality.
+     - Either:
+
+       .. code-block:: none
+
+           true
+
+       or:
+
+       .. code-block:: none
+
+                  false
+     - None, must supply this value.
+   * - .. code-block:: none
+
+          mp.messaging.outgoing.events-outgoing.bootstrap.servers
+
+       *Required*, if kafka enabled
+     - The kafka bootstrap server(s) to connect to.
+     - .. code-block:: none
+
+           OUTSIDE://{infra.kafka.host}:{infra.kafka.port}
+
+     - None, must supply this value (if kafka enabled).
+
+JWT Configuration
+=====================
+
+For JWT configuration, we leverage the settings as presented by Quarkus. For convenience, we have the most important configuration below, but
+further options can be found on the `Quarkus JWT Configuration <https://quarkus.io/guides/security-jwt#configuration-reference>`_ documentation.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Config Key
+     - Description
+     - Values (Examples)
+     - Default
+   * - .. code-block:: none
+
+          smallrye.jwt.verify.key.location
+
+       *Required*
+
+       Or, some configuration that provides the certs for JWT verification.
+     - The location of where to retrieve certs to verify JWT's. Config property allows for a specified external or internal
+       location of the public key. The value can be a relative path or a URL.
+     - .. code-block:: none
+
+          http://oqm-infra-keycloak:8080/realms/oqm/protocol/openid-connect/certs
+
+       .. code-block:: none
+
+          /path/to/cert.pub
+     - None, must supply this value.
+
+Metrics/OpenTelemetry Configuration
+=====================
+
+For OpenTelemetry configuration, we leverage the settings as presented by Quarkus. For convenience, we have the most important configuration below, but
+further options can be found on the `Quarkus OpenTelemetry Configuration <https://quarkus.io/guides/opentelemetry#configuration-reference>`_ documentation.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Config Key
+     - Description
+     - Values (Examples)
+     - Default
+   * - .. code-block:: none
+
+          quarkus.otel.exporter.otlp.endpoint
+
+     - Where to export OpenTelemetry metrics to.
+     - .. code-block:: none
+
+          http://#{host}:4317
+     - None.

software/core/oqm-core-api/docs/sphinx-test/source/running/04_mongo.rst

@@ -0,0 +1,11 @@
+MongoDB Reference
+#######################
+
+This guide is an explainer to how MongoDB is leveraged by the Core API
+
+Databases
+=========
+
+TODO
+
+

software/core/oqm-core-api/docs/sphinx-test/source/running/05_jwt.rst

@@ -0,0 +1,8 @@
+JWT Reference
+#######################
+
+This guide is an explainer to how JWT's are used by the Core API, and what needs to be included.
+
+
+
+

software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst

@@ -10,3 +10,6 @@ This section is concerned with how to run, configure, and otherwise manage your
 
    01_prerequisites
    02_basic_quickstart
+   03_configuration
+   04_mongo
+   05_jwt