From a57568cb46e2958ba2d5de073e8fe65cca67873e Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sat, 23 May 2026 02:29:39 -0400 Subject: [PATCH 01/13] Core - API - Fleshing out oqm core api docs --- docs/documentation.md | 7 ++++ .../oqm-core-api/docs/sphinx-test/.gitignore | 1 + .../oqm-core-api/docs/sphinx-test/Makefile | 20 +++++++++++ .../oqm-core-api/docs/sphinx-test/make.bat | 35 +++++++++++++++++++ .../sphinx-test/source/_templates/layout.html | 12 +++++++ .../docs/sphinx-test/source/conf.py | 29 +++++++++++++++ .../source/features/01_nonfunctional.rst | 18 ++++++++++ .../source/features/02_database.rst | 15 ++++++++ .../source/features/03_entitiesAuthRoles.rst | 28 +++++++++++++++ .../source/features/04_messaging.rst | 3 ++ .../source/features/05_filesImages.rst | 26 ++++++++++++++ .../sphinx-test/source/features/index.rst | 15 ++++++++ .../docs/sphinx-test/source/index.rst | 27 ++++++++++++++ .../docs/sphinx-test/source/running/index.rst | 6 ++++ 14 files changed, 242 insertions(+) create mode 100644 docs/documentation.md create mode 100644 software/core/oqm-core-api/docs/sphinx-test/.gitignore create mode 100644 software/core/oqm-core-api/docs/sphinx-test/Makefile create mode 100644 software/core/oqm-core-api/docs/sphinx-test/make.bat create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/conf.py create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/features/02_database.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/features/04_messaging.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/features/05_filesImages.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/index.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 000000000..ad2052cb8 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,7 @@ +# Documentation Guide + +## Sphinx + +``` +python3-sphinx +``` diff --git a/software/core/oqm-core-api/docs/sphinx-test/.gitignore b/software/core/oqm-core-api/docs/sphinx-test/.gitignore new file mode 100644 index 000000000..567609b12 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/software/core/oqm-core-api/docs/sphinx-test/Makefile b/software/core/oqm-core-api/docs/sphinx-test/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/software/core/oqm-core-api/docs/sphinx-test/make.bat b/software/core/oqm-core-api/docs/sphinx-test/make.bat new file mode 100644 index 000000000..dc1312ab0 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html b/software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html new file mode 100644 index 000000000..dd4285582 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html @@ -0,0 +1,12 @@ +{% extends "!layout.html" %} + +{% block menu %} +{{ super() }} +

+ Indices +

+ + +{% endblock %} diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py new file mode 100644 index 000000000..ffb9598be --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py @@ -0,0 +1,29 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'OQM Core API' +copyright = '2026, EBP' +author = 'Greg Stewart, EBP' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['source/_templates'] +exclude_patterns = [] + +numbered_sections = True + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst new file mode 100644 index 000000000..7d32b5eb4 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst @@ -0,0 +1,18 @@ +Nonfunctional Features +====================== + + +Scalability +----------- + +The service should support working in a clustered context, where many instances can work in tandem. + +Resource Usage +-------------- + +The service should not waste compute or resources, and be free of memory leaks. + +Metrics +------- + +The service supports passing on metrics to an external `OpenTelemetry `_ sync. diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/02_database.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/02_database.rst new file mode 100644 index 000000000..aec19d3f6 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/02_database.rst @@ -0,0 +1,15 @@ +Databases +========= + +Support Many Databases +---------------------- + +Initial Database +---------------- + +Database Creation +----------------- + +Database Deletion +----------------- + diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst new file mode 100644 index 000000000..910493c84 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst @@ -0,0 +1,28 @@ +Entities, Auth, and Roles +============================================ + + +.. index:: + single: Auth + +.. glossary:: + Interacting Entity + Any entity (user, service, plugin, etc) that is interacting with the system. + +JWT Based Auth +-------------- + +Entities are to authenticate themselves to the system with `JWT `_'s. + +.. TODO include required fields + +Roles +----- + +.. TODO list roles + +Keep track of entities interacting with the system +-------------------------------------------------- + +Allow entities to retrieve their own information +------------------------------------------------ diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/04_messaging.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/04_messaging.rst new file mode 100644 index 000000000..05a913a8b --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/04_messaging.rst @@ -0,0 +1,3 @@ +Messaging +========= + diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/05_filesImages.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/05_filesImages.rst new file mode 100644 index 000000000..47c9f899c --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/05_filesImages.rst @@ -0,0 +1,26 @@ +Files and Images +================ + +Add +--- + +Read Data +--------- + +Read Metadata +------------- + +Update File +----------- + +Update Metadata +--------------- + +Delete +------ + +Image Specific Requirements +--------------------------- + +Resizing +^^^^^^^^ diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst new file mode 100644 index 000000000..e67f253f6 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst @@ -0,0 +1,15 @@ +Requirements +============ + + + +.. toctree:: + :numbered: + :maxdepth: 2 + :caption: Requirement Groups: + + 01_nonfunctional + 02_database + 03_entitiesAuthRoles + 04_messaging + 05_filesImages diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst new file mode 100644 index 000000000..d9e47ae37 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst @@ -0,0 +1,27 @@ +.. OQM Core API documentation master file, created by + sphinx-quickstart on Fri May 22 23:49:45 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +OQM Core API +======================================== + +This project is the server providing the core functionality of Open QuarterMaster. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + running/index + features/index + + +Overview +================== + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst new file mode 100644 index 000000000..450aa99b7 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst @@ -0,0 +1,6 @@ +Running the Server +=========================== + +This section is concerned with how to run, configure, and otherwise manage your OQM Core API instance. + + From 60e15184dbf579e6107d792c6a011af3c6cfd27f Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sat, 23 May 2026 23:09:43 -0400 Subject: [PATCH 02/13] Core - API - Fleshing out oqm core api doc, cleanup of some unused utilities --- .../oqm-core-api/docs/sphinx-test/.gitignore | 1 + .../oqm-core-api/docs/sphinx-test/README.md | 17 ++ .../docs/sphinx-test/requirements.txt | 1 + .../docs/sphinx-test/source/_static/logo.svg | 65 +++++++ .../sphinx-test/source/_templates/layout.html | 12 -- .../docs/sphinx-test/source/conf.py | 17 +- .../source/features/03_entitiesAuthRoles.rst | 55 +++++- .../interactingEntity/InteractingEntity.java | 36 ++-- .../InteractingEntityType.java | 1 - .../externalService/plugin/Plugin.java | 46 ----- .../externalService/plugin/PluginService.java | 59 ------ .../externalService/plugin/PluginType.java | 15 -- .../plugin/PluginTypeType.java | 5 - .../plugin/components/nav/NavItem.java | 48 ----- .../plugin/components/nav/NavSubMenu.java | 46 ----- .../externalService/roles/RequestedRole.java | 29 --- .../externalService/GeneralServiceTest.java | 80 -------- .../PluginServiceSerializationTest.java | 33 ---- .../externalService/PluginServiceTest.java | 176 ------------------ 19 files changed, 165 insertions(+), 577 deletions(-) create mode 100644 software/core/oqm-core-api/docs/sphinx-test/README.md create mode 100644 software/core/oqm-core-api/docs/sphinx-test/requirements.txt create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/_static/logo.svg delete mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/Plugin.java delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginService.java delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginType.java delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginTypeType.java delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavItem.java delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavSubMenu.java delete mode 100644 software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/roles/RequestedRole.java delete mode 100644 software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/GeneralServiceTest.java delete mode 100644 software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceSerializationTest.java delete mode 100644 software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceTest.java diff --git a/software/core/oqm-core-api/docs/sphinx-test/.gitignore b/software/core/oqm-core-api/docs/sphinx-test/.gitignore index 567609b12..d925541b5 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/.gitignore +++ b/software/core/oqm-core-api/docs/sphinx-test/.gitignore @@ -1 +1,2 @@ build/ +.venv diff --git a/software/core/oqm-core-api/docs/sphinx-test/README.md b/software/core/oqm-core-api/docs/sphinx-test/README.md new file mode 100644 index 000000000..baef63bda --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/README.md @@ -0,0 +1,17 @@ +# Docs Building + +## Python Virtual env + +``` +$ python3 -m venv ./venv +$ source .venv/bin/activate +$ pip install -r requirements.txt +``` + +## Building Docs + +(in virtual environment) + +``` +make clean html +``` diff --git a/software/core/oqm-core-api/docs/sphinx-test/requirements.txt b/software/core/oqm-core-api/docs/sphinx-test/requirements.txt new file mode 100644 index 000000000..6966869c7 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/requirements.txt @@ -0,0 +1 @@ +sphinx diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/_static/logo.svg b/software/core/oqm-core-api/docs/sphinx-test/source/_static/logo.svg new file mode 100644 index 000000000..3479d6a00 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/_static/logo.svg @@ -0,0 +1,65 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html b/software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html deleted file mode 100644 index dd4285582..000000000 --- a/software/core/oqm-core-api/docs/sphinx-test/source/_templates/layout.html +++ /dev/null @@ -1,12 +0,0 @@ -{% extends "!layout.html" %} - -{% block menu %} -{{ super() }} -

- Indices -

- - -{% endblock %} diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py index ffb9598be..294d4cf23 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py +++ b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py @@ -16,7 +16,7 @@ extensions = [] -templates_path = ['source/_templates'] +templates_path = ['_templates'] exclude_patterns = [] numbered_sections = True @@ -27,3 +27,18 @@ html_theme = 'alabaster' html_static_path = ['_static'] +html_theme_options = { + "logo": "logo.svg", + "logo_name": True, + # 'show_related': True, + + 'github_user': 'Epic-Breakfast-Productions', + 'github_repo': 'OpenQuarterMaster', + 'github_banner': True, + "github_button": False, + "show_relbars": True + # 'github_count': True, + # 'extra_nav_links': { + # 'Index': 'genindex.html', + # } +} diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst index 910493c84..ea352396f 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst @@ -1,28 +1,69 @@ Entities, Auth, and Roles ============================================ +.. admonition:: Definitions -.. index:: - single: Auth - -.. glossary:: - Interacting Entity - Any entity (user, service, plugin, etc) that is interacting with the system. + .. glossary:: + Auth + The process of authenticating users and verifying credentials and permissions. + Interacting Entity + Any entity (user, service, plugin, etc) that is interacting with the system. + JWT + A `Json Web Token (JWT) `_ is a method for conveying information securely between entities, often + used to convey authorization after authentication with an external provider. JWT Based Auth -------------- -Entities are to authenticate themselves to the system with `JWT `_'s. +Entities are to authenticate themselves to the system with JWTs. +We consume JWT's to provide flexibility in auth provider, and the service is agnostic to any specific +JWT provider. .. TODO include required fields Roles ----- +The service uses roles in order to gatekeep if a particular interacting entity is allowed to access a given +resource. + .. TODO list roles Keep track of entities interacting with the system -------------------------------------------------- +All entities that interact with the system are to be registered in the system, and available for reference in other areas. + +Registration +^^^^^^^^^^^^ + +The first time an interacting entity interacts with the system, it is registered as an entity. + +Updates +^^^^^^^ + +When an entity interacts in subsequent requests, the information in the given JWT is checked against +the current values stored in the database. If information differs, it is updated. + Allow entities to retrieve their own information ------------------------------------------------ + +Entities are allowed to retrieve their own data held on them. + +Allow information to be retrieved on other entities +--------------------------------------------------- + +Others' full data +^^^^^^^^^^^^^^^^^ + +Others' Reference +^^^^^^^^^^^^^^^^^ + +Entities should be able to retrieve a reference object for any other entity, containing a bare minimum of data about the other entity. +Used to make sure UI's can properly display basic entity information in context. + + + + + + diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntity.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntity.java index 68a2fd5b0..528b6e471 100644 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntity.java +++ b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntity.java @@ -17,7 +17,6 @@ import tech.ebp.oqm.core.api.config.CoreApiInteractingEntity; import tech.ebp.oqm.core.api.model.object.AttKeywordMainObject; import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.GeneralService; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.PluginService; import tech.ebp.oqm.core.api.model.object.interactingEntity.user.User; import tech.ebp.oqm.core.api.service.JwtUtils; @@ -35,7 +34,6 @@ ) @JsonSubTypes({ @JsonSubTypes.Type(value = User.class, name = "USER"), - @JsonSubTypes.Type(value = PluginService.class, name = "SERVICE_PLUGIN"), @JsonSubTypes.Type(value = GeneralService.class, name = "SERVICE_GENERAL"), @JsonSubTypes.Type(value = CoreApiInteractingEntity.class, name = "CORE_API"), }) @@ -46,38 +44,38 @@ @EqualsAndHashCode(callSuper = true) @ToString(callSuper = true) @SuperBuilder(toBuilder = true) -@Schema(oneOf = {User.class, PluginService.class, GeneralService.class, CoreApiInteractingEntity.class}) +@Schema(oneOf = {User.class, GeneralService.class, CoreApiInteractingEntity.class}) public abstract class InteractingEntity extends AttKeywordMainObject { - + public static final int CUR_SCHEMA_VERSION = 2; - + @Schema(description = "The id of the entity from the auth provider. This is used to link the user as kept track of here to the auth provider.") private String idFromAuthProvider; - + private String authProvider; - + public abstract String getName(); - + public abstract String getEmail(); - + public abstract InteractingEntityType getType(); - + public abstract Set getRoles(); - + public abstract boolean updateFrom(JsonWebToken jwt); - + public static InteractingEntity createEntity(JsonWebToken jwt) { InteractingEntity newEntity; - + //TODO:: support services better. Probably should setup keycloak to set some of these values. if (((String) jwt.getClaim(Claims.upn)).startsWith("service-account-")) { GeneralService newService = new GeneralService(); - + newService.setName(jwt.getClaim(Claims.upn)); newService.setDescription("Service account from OIDC provider."); newService.setDeveloperEmail("foo@bar.com"); newService.setDeveloperName("Developers"); - + newEntity = newService; } else { User newUser = new User(); @@ -89,19 +87,19 @@ public static InteractingEntity createEntity(JsonWebToken jwt) { } newEntity.setAuthProvider(jwt.getIssuer()); newEntity.setIdFromAuthProvider(jwt.getSubject()); - + log.debug("New entity: {}", newEntity); return newEntity; } - + public static InteractingEntity createEntity(SecurityContext context) { User newUser = new User(); newUser.setName(context.getUserPrincipal().getName()); - + log.debug("New entity: {}", newUser); return newUser; } - + @Override public int getSchemaVersion() { return CUR_SCHEMA_VERSION; diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntityType.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntityType.java index 6d927a1d3..e272a0824 100644 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntityType.java +++ b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/InteractingEntityType.java @@ -3,6 +3,5 @@ public enum InteractingEntityType { USER, SERVICE_GENERAL, - SERVICE_PLUGIN, CORE_API } diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/Plugin.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/Plugin.java deleted file mode 100644 index 1f94e0bfc..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/Plugin.java +++ /dev/null @@ -1,46 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin; - -import com.fasterxml.jackson.annotation.JsonProperty; -import com.fasterxml.jackson.annotation.JsonSubTypes; -import com.fasterxml.jackson.annotation.JsonTypeInfo; -import jakarta.validation.constraints.NotBlank; -import jakarta.validation.constraints.NotNull; -import lombok.Data; -import lombok.NoArgsConstructor; -import lombok.NonNull; -import lombok.experimental.SuperBuilder; -import org.bson.codecs.pojo.annotations.BsonDiscriminator; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.components.nav.NavItem; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.components.nav.NavSubMenu; - -@Data -//@AllArgsConstructor -@NoArgsConstructor -@JsonTypeInfo( - use = JsonTypeInfo.Id.NAME, - include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "pluginType" -) -@JsonSubTypes({ - @JsonSubTypes.Type(value = NavItem.class, name = "NAV_ITEM"), - @JsonSubTypes.Type(value = NavSubMenu.class, name = "NAV_SUB_MENU"), -}) -@BsonDiscriminator() -@SuperBuilder -public abstract class Plugin { - - // @lombok.Builder.Default - // public boolean enabled = true; - - @NonNull - @NotNull - @NotBlank - public String name; - - @NonNull - @NotNull - @lombok.Builder.Default - public String description = ""; - - @JsonProperty(access = JsonProperty.Access.READ_ONLY) - public abstract PluginType getPluginType(); -} diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginService.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginService.java deleted file mode 100644 index 939396f11..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginService.java +++ /dev/null @@ -1,59 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin; - -import com.fasterxml.jackson.annotation.JsonProperty; -import jakarta.validation.constraints.NotNull; -import lombok.AllArgsConstructor; -import lombok.Data; -import lombok.EqualsAndHashCode; -import lombok.NoArgsConstructor; -import lombok.NonNull; -import lombok.ToString; -import lombok.experimental.SuperBuilder; -import org.eclipse.microprofile.jwt.JsonWebToken; -import org.eclipse.microprofile.openapi.annotations.media.Schema; -import tech.ebp.oqm.core.api.model.object.interactingEntity.InteractingEntityType; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.ExternalService; - -import java.util.ArrayList; -import java.util.List; - -@Data -@NoArgsConstructor -@AllArgsConstructor -@EqualsAndHashCode(callSuper = true) -@ToString(callSuper = true) -@SuperBuilder(toBuilder = true) -@Schema(title = "PluginService", description = "A service that self-identifies as a plugin.") -public class PluginService extends ExternalService { - - @NonNull - @NotNull - @lombok.Builder.Default - List enabledPageComponents = new ArrayList<>(); - - @NonNull - @NotNull - @lombok.Builder.Default - List disabledPageComponents = new ArrayList<>(); - - public List getAllPlugins() { - List output = new ArrayList<>(); - output.addAll(this.getEnabledPageComponents()); - output.addAll(this.getDisabledPageComponents()); - - return output; - } - - @JsonProperty(access = JsonProperty.Access.READ_ONLY) - @Override - @Schema(constValue = "SERVICE_PLUGIN", readOnly = true, required = true, examples = "SERVICE_PLUGIN") - public InteractingEntityType getType() { - return InteractingEntityType.SERVICE_PLUGIN; - } - - @Override - public boolean updateFrom(JsonWebToken jwt) { - //TODO - return false; - } -} diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginType.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginType.java deleted file mode 100644 index cb042e2c9..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginType.java +++ /dev/null @@ -1,15 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin; - -/** - * Other ideas: - Overview page tab entry - */ -public enum PluginType { - NAV_ITEM(PluginTypeType.PAGE_COMPONENT), - NAV_SUB_MENU(PluginTypeType.PAGE_COMPONENT); - - public final PluginTypeType type; - - PluginType(PluginTypeType type) { - this.type = type; - } -} diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginTypeType.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginTypeType.java deleted file mode 100644 index 22c300833..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/PluginTypeType.java +++ /dev/null @@ -1,5 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin; - -public enum PluginTypeType { - PAGE_COMPONENT; -} diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavItem.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavItem.java deleted file mode 100644 index bf2478b9b..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavItem.java +++ /dev/null @@ -1,48 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.components.nav; - -import jakarta.validation.constraints.NotNull; -import lombok.AllArgsConstructor; -import lombok.Data; -import lombok.EqualsAndHashCode; -import lombok.NoArgsConstructor; -import lombok.NonNull; -import lombok.ToString; -import lombok.experimental.SuperBuilder; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.Plugin; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.PluginType; - -import java.net.URL; - -@Data -@NoArgsConstructor -@AllArgsConstructor -@EqualsAndHashCode(callSuper = true) -@ToString(callSuper = true) -@SuperBuilder -public class NavItem extends Plugin { - - @Override - public PluginType getPluginType() { - return PluginType.NAV_ITEM; - } - - /** - * The text of the link - */ - @NonNull - @NotNull - private String itemText; - - /** - * The url of the nav item to go to - */ - @NonNull - @NotNull - private URL itemUrl; - - /** - * If the link should go to a new tab - */ - @lombok.Builder.Default - private boolean newTab = false; -} diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavSubMenu.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavSubMenu.java deleted file mode 100644 index 731ad68b9..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/plugin/components/nav/NavSubMenu.java +++ /dev/null @@ -1,46 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.components.nav; - -import jakarta.validation.constraints.NotEmpty; -import jakarta.validation.constraints.NotNull; -import lombok.AllArgsConstructor; -import lombok.Data; -import lombok.EqualsAndHashCode; -import lombok.NoArgsConstructor; -import lombok.NonNull; -import lombok.ToString; -import lombok.experimental.SuperBuilder; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.Plugin; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.PluginType; - -import java.util.ArrayList; -import java.util.List; - -@Data -@NoArgsConstructor -@AllArgsConstructor -@EqualsAndHashCode(callSuper = true) -@ToString(callSuper = true) -@SuperBuilder -public class NavSubMenu extends Plugin { - - @Override - public PluginType getPluginType() { - return PluginType.NAV_SUB_MENU; - } - - /** - * The text of the menu - */ - @NonNull - @NotNull - private String menuText; - - /** - * The list of nav items to show in the menu - */ - @NotNull - @NonNull - @NotEmpty - @lombok.Builder.Default - private List menuItems = new ArrayList<>(); -} diff --git a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/roles/RequestedRole.java b/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/roles/RequestedRole.java deleted file mode 100644 index aca160d43..000000000 --- a/software/core/oqm-core-api/src/main/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/roles/RequestedRole.java +++ /dev/null @@ -1,29 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.roles; - -import jakarta.validation.constraints.NotBlank; -import jakarta.validation.constraints.NotNull; -import lombok.AllArgsConstructor; -import lombok.Data; -import lombok.NoArgsConstructor; -import lombok.NonNull; -import tech.ebp.oqm.core.api.model.validation.annotations.ValidServiceRole; - -@Data -@AllArgsConstructor -@NoArgsConstructor -public class RequestedRole { - - @NonNull - @NotNull - @NotBlank - @ValidServiceRole - public String role; - - @NonNull - @NotNull - @NotBlank - @ValidServiceRole - private String reason; - - private boolean optional = true; -} diff --git a/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/GeneralServiceTest.java b/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/GeneralServiceTest.java deleted file mode 100644 index 288a30436..000000000 --- a/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/GeneralServiceTest.java +++ /dev/null @@ -1,80 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService; - -import lombok.extern.slf4j.Slf4j; -import org.junit.jupiter.params.provider.Arguments; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.roles.RequestedRole; -import tech.ebp.oqm.core.api.model.rest.auth.roles.ServiceRoles; - -import java.util.Set; -import java.util.stream.Stream; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertNotNull; - -//@Slf4j -//public class GeneralServiceTest extends ExternalServiceTest { -// -// -// public static Stream getUnchangedExtServices() { -// GeneralService s = new GeneralService(); -// s.setName(FAKER.name().name()) -// .setDescription(FAKER.lorem().paragraph()) -// .setDeveloperName(FAKER.name().name()) -// .setDeveloperEmail(FAKER.internet().emailAddress()); -// -// GeneralServiceSetupRequest r = GeneralServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .build(); -// -// return Stream.of( -// Arguments.of(s, r) -// ); -// } -// -// public static Stream getChangedExtServices() { -// GeneralService s = new GeneralService(); -// s.setName(FAKER.name().name()) -// .setDescription(FAKER.lorem().paragraph()) -// .setDeveloperName(FAKER.name().name()) -// .setDeveloperEmail(FAKER.internet().emailAddress()); -// -// return Stream.of( -// Arguments.of(s, GeneralServiceSetupRequest.builder() -// .name(FAKER.name().name()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .build()), -// Arguments.of(s, GeneralServiceSetupRequest.builder() -// .name(s.getName()) -// .description(FAKER.lorem().paragraph()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .build()), -// Arguments.of(s, GeneralServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(FAKER.name().name()) -// .developerEmail(s.getDeveloperEmail()) -// .build()), -// Arguments.of(s, GeneralServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(FAKER.internet().emailAddress()) -// .build()), -// Arguments.of(s, GeneralServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .requestedRoles(Set.of( -// new RequestedRole(ServiceRoles.SERVICE_ROLES.get(1), "To do the thing 2", true) -// )) -// .build()) -// ); -// } -//} \ No newline at end of file diff --git a/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceSerializationTest.java b/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceSerializationTest.java deleted file mode 100644 index 19bb77d4e..000000000 --- a/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceSerializationTest.java +++ /dev/null @@ -1,33 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService; - -import lombok.extern.slf4j.Slf4j; -import org.bson.types.ObjectId; -import org.junit.jupiter.params.provider.Arguments; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.PluginService; -import tech.ebp.oqm.core.api.model.testUtils.ObjectSerializationTest; - -import java.util.stream.Stream; - -@Slf4j -class PluginServiceSerializationTest extends ObjectSerializationTest { - - protected PluginServiceSerializationTest() { - super(PluginService.class); - } - - public static Stream getObjects() { - return Stream.of( - Arguments.of( - new PluginService() - .setName(FAKER.name().name()) - .setDeveloperName(FAKER.name().name()) - .setDeveloperEmail(FAKER.internet().emailAddress()) - .setAuthProvider("keycloak") - .setIdFromAuthProvider("id") - .setId(ObjectId.get()) - - ) - ); - } - -} \ No newline at end of file diff --git a/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceTest.java b/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceTest.java deleted file mode 100644 index 3e0708f5f..000000000 --- a/software/core/oqm-core-api/src/test/java/tech/ebp/oqm/core/api/model/object/interactingEntity/externalService/PluginServiceTest.java +++ /dev/null @@ -1,176 +0,0 @@ -package tech.ebp.oqm.core.api.model.object.interactingEntity.externalService; - -import lombok.extern.slf4j.Slf4j; -import org.junit.jupiter.params.provider.Arguments; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.PluginService; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.plugin.components.nav.NavItem; -import tech.ebp.oqm.core.api.model.object.interactingEntity.externalService.roles.RequestedRole; -import tech.ebp.oqm.core.api.model.rest.auth.roles.ServiceRoles; - -import java.net.MalformedURLException; -import java.net.URL; -import java.util.List; -import java.util.Set; -import java.util.stream.Stream; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertNotNull; - -//@Slf4j -//public class PluginServiceTest extends ExternalServiceTest { -// -// -// public static Stream getUnchangedExtServices() throws MalformedURLException { -// PluginService s = new PluginService(); -// s.setName(FAKER.name().name()) -// .setDescription(FAKER.lorem().paragraph()) -// .setDeveloperName(FAKER.name().name()) -// .setDeveloperEmail(FAKER.internet().emailAddress()) -// ; -// s.setDisabledPageComponents( -// List.of( -// NavItem.builder() -// .name(FAKER.name().name()) -// .itemText(FAKER.lorem().sentence()) -// .itemUrl(new URL("https://" + FAKER.internet().url())) -// .build() -// ) -// ); -// s.setEnabledPageComponents( -// List.of( -// NavItem.builder() -// .name(FAKER.name().name()) -// .itemText(FAKER.lorem().sentence()) -// .itemUrl(new URL("https://" + FAKER.internet().url())) -// .build() -// ) -// ); -// -// PluginServiceSetupRequest r = PluginServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0), -// s.getEnabledPageComponents().get(0) -// ) -// ) -// .build(); -// -// return Stream.of( -// Arguments.of(s, r) -// ); -// } -// -// public static Stream getChangedExtServices() throws MalformedURLException { -// PluginService s = new PluginService(); -// s.setName(FAKER.name().name()) -// .setDescription(FAKER.lorem().paragraph()) -// .setDeveloperName(FAKER.name().name()) -// .setDeveloperEmail(FAKER.internet().emailAddress()); -// s.setDisabledPageComponents( -// List.of( -// NavItem.builder() -// .name(FAKER.name().name()) -// .itemText(FAKER.lorem().sentence()) -// .itemUrl(new URL("https://" + FAKER.internet().url())) -// .build() -// ) -// ); -// s.setEnabledPageComponents( -// List.of( -// NavItem.builder() -// .name(FAKER.name().name()) -// .itemText(FAKER.lorem().sentence()) -// .itemUrl(new URL("https://" + FAKER.internet().url())) -// .build() -// ) -// ); -// -// return Stream.of( -// Arguments.of(s, PluginServiceSetupRequest.builder() -// .name(FAKER.name().name()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0), -// s.getEnabledPageComponents().get(0) -// ) -// ) -// .build() -// ), -// Arguments.of(s, PluginServiceSetupRequest.builder() -// .name(s.getName()) -// .description(FAKER.lorem().paragraph()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0), -// s.getEnabledPageComponents().get(0) -// ) -// ) -// .build() -// ), -// Arguments.of(s, PluginServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(FAKER.name().name()) -// .developerEmail(s.getDeveloperEmail()) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0), -// s.getEnabledPageComponents().get(0) -// ) -// ) -// .build() -// ), -// Arguments.of(s, PluginServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(FAKER.internet().emailAddress()) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0), -// s.getEnabledPageComponents().get(0) -// ) -// ) -// .build() -// ), -// Arguments.of(s, PluginServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .requestedRoles(Set.of( -// new RequestedRole(ServiceRoles.SERVICE_ROLES.get(1), "To do the thing 2", true) -// )) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0), -// s.getEnabledPageComponents().get(0) -// ) -// ) -// .build() -// ), -// Arguments.of(s, PluginServiceSetupRequest.builder() -// .name(s.getName()) -// .description(s.getDescription()) -// .developerName(s.getDeveloperName()) -// .developerEmail(s.getDeveloperEmail()) -// .pageComponents( -// List.of( -// s.getDisabledPageComponents().get(0) -// ) -// ) -// .build() -// ) -// ); -// } -// -//} From a437b5cf35b224353a9f11e0941d6a1f7006eeb5 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sun, 24 May 2026 00:42:19 -0400 Subject: [PATCH 03/13] Core - API - Fleshing out more core api docs --- .../docs/sphinx-test/source/conf.py | 10 ++++- .../sphinx-test/source/design_decisions.rst | 32 ++++++++++++++ .../source/features/03_entitiesAuthRoles.rst | 2 + .../sphinx-test/source/features/index.rst | 2 +- .../docs/sphinx-test/source/index.rst | 4 +- .../source/running/01_prerequisites.rst | 42 +++++++++++++++++++ .../docs/sphinx-test/source/running/index.rst | 5 +++ 7 files changed, 94 insertions(+), 3 deletions(-) create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/running/01_prerequisites.rst diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py index 294d4cf23..5c04f1f46 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py +++ b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py @@ -8,7 +8,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'OQM Core API' -copyright = '2026, EBP' +copyright = '2026, EBP' author = 'Greg Stewart, EBP' # -- General configuration --------------------------------------------------- @@ -42,3 +42,11 @@ # 'Index': 'genindex.html', # } } +html_sidebars = { + '**': [ + 'about.html', + 'localtoc.html', + 'navigation.html', + 'searchbox.html', + ] +} diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst new file mode 100644 index 000000000..2dfd38968 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst @@ -0,0 +1,32 @@ +####################################### +Design Decisions +####################################### + +This document is intended to outline the why and how of our decisions regarding the way we have built out the service. + +Operational / Architecture Decisions +==================================== + +Quarkus +------- + +MongoDB +------- + +JWT Auth +-------- + +Kafka Messaging +--------------- + +Optionality +^^^^^^^^^^^ + +OpenTelemetry +------------- + +Optionality +^^^^^^^^^^^ + +Functional / Design Decisions (major) +===================================== diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst index ea352396f..a8a210fa8 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/03_entitiesAuthRoles.rst @@ -6,8 +6,10 @@ Entities, Auth, and Roles .. glossary:: Auth The process of authenticating users and verifying credentials and permissions. + Interacting Entity Any entity (user, service, plugin, etc) that is interacting with the system. + JWT A `Json Web Token (JWT) `_ is a method for conveying information securely between entities, often used to convey authorization after authentication with an external provider. diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst index e67f253f6..635624fc8 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst @@ -1,7 +1,7 @@ Requirements ============ - +This is a comprehensive set of requirements to describe high level capabilities and features of the Core API service. .. toctree:: :numbered: diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst index d9e47ae37..497f62bb1 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst @@ -3,8 +3,9 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +####################################### OQM Core API -======================================== +####################################### This project is the server providing the core functionality of Open QuarterMaster. @@ -14,6 +15,7 @@ This project is the server providing the core functionality of Open QuarterMaste running/index features/index + design_decisions Overview diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/running/01_prerequisites.rst b/software/core/oqm-core-api/docs/sphinx-test/source/running/01_prerequisites.rst new file mode 100644 index 000000000..2dfe13a33 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/running/01_prerequisites.rst @@ -0,0 +1,42 @@ +Prerequisites +============= + +Required +-------- + +System +^^^^^^ + +* CPU: ARM or x64 +* Memory: ~500Mb reasonable minimum, depending +* Docker / Podman / Container Runtime + +MongoDB +^^^^^^^ + +Mongodb is the backend database for the core api. + +JWT Provider / Token +^^^^^^^^^^^^^^^^^^^^ + +The JWT needs to be granted by an additional authority. Example being Keycloak. + +Optional +-------- + +These are optional setups that can be tied into the system. + +Kafka Instance +^^^^^^^^^^^^^^ + +The core api is capable of optionally connecting to a Kafka instance to leverage message-based patterns. + +OpenTelemetry +^^^^^^^^^^^^^^ + +You can have the core api pass on metrics, traces, logs to an OpenTelemetry endpoint. + +SSL Cert +^^^^^^^^ + +You can optionally configure a SSL cert to enable HTTPS. You will have to have this provided. diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst index 450aa99b7..b6fae2305 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst @@ -4,3 +4,8 @@ Running the Server This section is concerned with how to run, configure, and otherwise manage your OQM Core API instance. +.. toctree:: + :maxdepth: 2 + :caption: Requirement Groups: + + 01_prerequisites From c99e8da337059756f75c71b8a4647c04e3a76998 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sun, 24 May 2026 01:06:16 -0400 Subject: [PATCH 04/13] Core - API - more doc work --- .../docs/sphinx-test/source/design_decisions.rst | 9 +++++++++ .../sphinx-test/source/features/01_nonfunctional.rst | 5 +++++ .../docs/sphinx-test/source/features/index.rst | 5 +++++ .../sphinx-test/source/running/02_basic_quickstart.rst | 2 ++ .../docs/sphinx-test/source/running/index.rst | 1 + 5 files changed, 22 insertions(+) create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/running/02_basic_quickstart.rst diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst index 2dfd38968..8aa615fa1 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst @@ -7,9 +7,15 @@ This document is intended to outline the why and how of our decisions regarding Operational / Architecture Decisions ==================================== +This section talks to how we arrived at the decisions surrounding how we have guild the service, and +why we chose the tools we did. + Quarkus ------- +Container Deployment +-------------------- + MongoDB ------- @@ -30,3 +36,6 @@ Optionality Functional / Design Decisions (major) ===================================== + +This section goes over why we implemented certain high level functionalities they way we did. +We won't go too deep into every tiny design choice, but will talk to higher level design patterns. diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst index 7d32b5eb4..5cfa5df06 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/01_nonfunctional.rst @@ -16,3 +16,8 @@ Metrics ------- The service supports passing on metrics to an external `OpenTelemetry `_ sync. + +Deployment +---------- + +The service is deployed using Containers. This is the only method for deployment we support. diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst index 635624fc8..243e8b270 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst @@ -3,6 +3,11 @@ Requirements This is a comprehensive set of requirements to describe high level capabilities and features of the Core API service. +Intended as a traceable, authoritative itemization of requirements to trace functionalities, code, tests, and documentation back to. + +Is NOT a low level implementation detailed document, rather a higher level set of generalized capabilities, requirements, and features. +This mean that things like specific data models, implementation details, and similar low level information is not here. + .. toctree:: :numbered: :maxdepth: 2 diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/running/02_basic_quickstart.rst b/software/core/oqm-core-api/docs/sphinx-test/source/running/02_basic_quickstart.rst new file mode 100644 index 000000000..d03a8b32f --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/running/02_basic_quickstart.rst @@ -0,0 +1,2 @@ +Basic Quickstart +################ diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst index b6fae2305..7edec7fec 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/running/index.rst @@ -9,3 +9,4 @@ This section is concerned with how to run, configure, and otherwise manage your :caption: Requirement Groups: 01_prerequisites + 02_basic_quickstart From 00be0ef6a790dd33caf39f48bfdfde59165a19d8 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sun, 24 May 2026 01:16:10 -0400 Subject: [PATCH 05/13] Core - API - adding user guide section to docs --- .../oqm-core-api/docs/sphinx-test/source/index.rst | 1 + .../docs/sphinx-test/source/usage/01_main_ideas.rst | 2 ++ .../docs/sphinx-test/source/usage/index.rst | 11 +++++++++++ 3 files changed, 14 insertions(+) create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/usage/01_main_ideas.rst create mode 100644 software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst index 497f62bb1..21154ecea 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst @@ -14,6 +14,7 @@ This project is the server providing the core functionality of Open QuarterMaste :caption: Contents: running/index + usage/index features/index design_decisions diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/usage/01_main_ideas.rst b/software/core/oqm-core-api/docs/sphinx-test/source/usage/01_main_ideas.rst new file mode 100644 index 000000000..d579f01d6 --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/usage/01_main_ideas.rst @@ -0,0 +1,2 @@ +Main Ideas +============= diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst new file mode 100644 index 000000000..03b6ffc0b --- /dev/null +++ b/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst @@ -0,0 +1,11 @@ +Usage / User Guide +##################### + +This section is concerned with how actually use the service. + + +.. toctree:: + :maxdepth: 2 + :caption: Topics: + + 01_main_ideas From aedf813f116753af9057cab461d554601012a562 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sun, 24 May 2026 13:17:25 -0400 Subject: [PATCH 06/13] Documentation Improvements, adding overall documentation site code --- docs/documentation.md | 4 ++ docs/sphinx/.gitignore | 1 + docs/sphinx/Makefile | 20 ++++++ docs/sphinx/make.bat | 35 ++++++++++ docs/sphinx/requirements.txt | 1 + docs/sphinx/source/_static/logo.svg | 65 +++++++++++++++++++ docs/sphinx/source/components.rst | 24 +++++++ docs/sphinx/source/conf.py | 50 ++++++++++++++ docs/sphinx/source/deployment.rst | 10 +++ docs/sphinx/source/index.rst | 28 ++++++++ .../oqm-core-api/docs/sphinx-test/README.md | 2 +- .../docs/sphinx-test/source/conf.py | 2 +- .../sphinx-test/source/design_decisions.rst | 2 +- .../docs/sphinx-test/source/index.rst | 2 + 14 files changed, 243 insertions(+), 3 deletions(-) create mode 100644 docs/sphinx/.gitignore create mode 100644 docs/sphinx/Makefile create mode 100644 docs/sphinx/make.bat create mode 100644 docs/sphinx/requirements.txt create mode 100644 docs/sphinx/source/_static/logo.svg create mode 100644 docs/sphinx/source/components.rst create mode 100644 docs/sphinx/source/conf.py create mode 100644 docs/sphinx/source/deployment.rst create mode 100644 docs/sphinx/source/index.rst diff --git a/docs/documentation.md b/docs/documentation.md index ad2052cb8..ceb6eb211 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -5,3 +5,7 @@ ``` python3-sphinx ``` + +``` +sphinx-build -M html ./source/ ./build/ +``` diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore new file mode 100644 index 000000000..567609b12 --- /dev/null +++ b/docs/sphinx/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/docs/sphinx/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/sphinx/make.bat b/docs/sphinx/make.bat new file mode 100644 index 000000000..dc1312ab0 --- /dev/null +++ b/docs/sphinx/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt new file mode 100644 index 000000000..6966869c7 --- /dev/null +++ b/docs/sphinx/requirements.txt @@ -0,0 +1 @@ +sphinx diff --git a/docs/sphinx/source/_static/logo.svg b/docs/sphinx/source/_static/logo.svg new file mode 100644 index 000000000..3479d6a00 --- /dev/null +++ b/docs/sphinx/source/_static/logo.svg @@ -0,0 +1,65 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + diff --git a/docs/sphinx/source/components.rst b/docs/sphinx/source/components.rst new file mode 100644 index 000000000..ecca2541f --- /dev/null +++ b/docs/sphinx/source/components.rst @@ -0,0 +1,24 @@ +.. Open QuarterMaster documentation master file, created by + sphinx-quickstart on Sun May 24 11:57:35 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Components +############################# + +Open QuarterMaster is a modular system, and has a few different components. Listed below are the different components and links to their individual documentation. + +\+ = Documentation coming soon + +Core Components +=============== + +* `Core API `_ - The Core service in charge of handling all inventory management tasks +* Characteristics+ +* Base Station+ + +Plugins +======= + +* External Item Search+ +* Storagotchi+ diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py new file mode 100644 index 000000000..f23452323 --- /dev/null +++ b/docs/sphinx/source/conf.py @@ -0,0 +1,50 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Open QuarterMaster' +copyright = '2026, EBP' +author = 'Greg Stewart, EBP' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] +html_theme_options = { + "logo": "logo.svg", + "logo_name": False, + # 'show_related': True, + + 'github_user': 'Epic-Breakfast-Productions', + 'github_repo': 'OpenQuarterMaster', + 'github_banner': True, + "github_button": False, + "show_relbars": True + # 'github_count': True, + # 'extra_nav_links': { + # 'Index': 'genindex.html', + # } +} +html_sidebars = { + '**': [ + 'about.html', + 'localtoc.html', + 'navigation.html', + 'searchbox.html', + ] +} diff --git a/docs/sphinx/source/deployment.rst b/docs/sphinx/source/deployment.rst new file mode 100644 index 000000000..3e36ba708 --- /dev/null +++ b/docs/sphinx/source/deployment.rst @@ -0,0 +1,10 @@ +Deployment +############################# + +Open Quartermaster is designed to be flexible to different forms of deployment. Below are links to our specific guides on the different ways you can deploy OQM: + +\+ = Coming Soon + +* +Single Node Host - The preferred way to deploy OQM on a single host. Full featured and production ready. +* +Kubernetes Operator - The preferred way to deploy OQM on a Kubernetes cluster. +* +Compose File - A barebones deployment of OQM, running with just core services. Use for tinkering, exploration, and development. diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst new file mode 100644 index 000000000..3dee70b82 --- /dev/null +++ b/docs/sphinx/source/index.rst @@ -0,0 +1,28 @@ +.. Open QuarterMaster documentation master file, created by + sphinx-quickstart on Sun May 24 11:57:35 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Open QuarterMaster Documentation +================================ + +.. image:: https://img.shields.io/github/commit-activity/m/Epic-Breakfast-Productions/OpenQuarterMaster + :target: https://img.shields.io/github/commit-activity/m/Epic-Breakfast-Productions/OpenQuarterMaster + :alt: Git Commit Activity + + +Welcome to the Open QuarterMaster docs! This site is a comprehensive look at everything Open QuarterMaster! + +Open Quartermaster is an open source inventory management system, designed to be simple to use yet powerful and extendable. The last inventory management system you will ever need! + +Quick Links +----------- + +* `OQM Website `_ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + deployment + components diff --git a/software/core/oqm-core-api/docs/sphinx-test/README.md b/software/core/oqm-core-api/docs/sphinx-test/README.md index baef63bda..78b9d8549 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/README.md +++ b/software/core/oqm-core-api/docs/sphinx-test/README.md @@ -3,7 +3,7 @@ ## Python Virtual env ``` -$ python3 -m venv ./venv +$ python3 -m venv ./.venv $ source .venv/bin/activate $ pip install -r requirements.txt ``` diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py index 5c04f1f46..6b4c8b07e 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/conf.py +++ b/software/core/oqm-core-api/docs/sphinx-test/source/conf.py @@ -7,7 +7,7 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'OQM Core API' +project = 'Core API' copyright = '2026, EBP' author = 'Greg Stewart, EBP' diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst index 8aa615fa1..44cfb273a 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst @@ -7,7 +7,7 @@ This document is intended to outline the why and how of our decisions regarding Operational / Architecture Decisions ==================================== -This section talks to how we arrived at the decisions surrounding how we have guild the service, and +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 diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst index 21154ecea..304fb2f2f 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/index.rst @@ -7,6 +7,8 @@ OQM Core API ####################################### +`Back to Overall Docs `_ + This project is the server providing the core functionality of Open QuarterMaster. .. toctree:: From 5a8196fd1ba54d86f7c31db2e0861bb7b1f0bd44 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sun, 24 May 2026 22:26:08 -0400 Subject: [PATCH 07/13] Documentation Improvements --- docs/sphinx/.gitignore | 1 + docs/sphinx/source/components.rst | 14 ++++++++------ docs/sphinx/source/deployment.rst | 6 +++--- docs/sphinx/source/index.rst | 1 + 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore index 567609b12..e7f9d2561 100644 --- a/docs/sphinx/.gitignore +++ b/docs/sphinx/.gitignore @@ -1 +1,2 @@ build/ +.venv/ diff --git a/docs/sphinx/source/components.rst b/docs/sphinx/source/components.rst index ecca2541f..86463f212 100644 --- a/docs/sphinx/source/components.rst +++ b/docs/sphinx/source/components.rst @@ -8,17 +8,19 @@ Components Open QuarterMaster is a modular system, and has a few different components. Listed below are the different components and links to their individual documentation. -\+ = Documentation coming soon - Core Components =============== +These are the components that make up the core functionalities of the system. Any OQM system is expected to include these. + * `Core API `_ - The Core service in charge of handling all inventory management tasks -* Characteristics+ -* Base Station+ +* `Characteristics `_ - Service for disseminating characteristics about a system, including who runs it, custom logos, etc. +* `Base Station `_ - The main frontend of the OQM system. Intended as a close to 1:1 feature parity for the core api backend. Plugins ======= -* External Item Search+ -* Storagotchi+ +Plugins are how we achieve our modular system. They add onto the core functionalities and enhance the experience with tailored experiences and tools. + +* `External Item Search `_ - A tool to get information about items from external sources. +* `Storagotchi `_ - A fun virtual pet to encourage inventory management. diff --git a/docs/sphinx/source/deployment.rst b/docs/sphinx/source/deployment.rst index 3e36ba708..a4c281a3b 100644 --- a/docs/sphinx/source/deployment.rst +++ b/docs/sphinx/source/deployment.rst @@ -5,6 +5,6 @@ Open Quartermaster is designed to be flexible to different forms of deployment. \+ = Coming Soon -* +Single Node Host - The preferred way to deploy OQM on a single host. Full featured and production ready. -* +Kubernetes Operator - The preferred way to deploy OQM on a Kubernetes cluster. -* +Compose File - A barebones deployment of OQM, running with just core services. Use for tinkering, exploration, and development. +* `Single Node Host `_ - The preferred way to deploy OQM on a single host. Full featured and production ready. +* \+ `Kubernetes Operator `_ - The preferred way to deploy OQM on a Kubernetes cluster. +* `Compose File `_ - A barebones deployment of OQM, running with just core services. Use for tinkering, exploration, and development. diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 3dee70b82..afa52eb8f 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -19,6 +19,7 @@ Quick Links ----------- * `OQM Website `_ +* `OQM Github `_ .. toctree:: :maxdepth: 2 From 6dc641840da9a18432abcd24f75accfca617a8f3 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Sun, 24 May 2026 22:36:49 -0400 Subject: [PATCH 08/13] Core - Characteristics - Added functionality to reload ui data if urls are not yet set in a single host deployment. Added homepage as a dependency for characteristics --- software/core/oqm-core-characteristics/app/UIs.py | 9 +++++++-- .../installerSrc/installerProperties.json | 2 +- .../installerSrc/oqm-core-characteristics.service | 2 +- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/software/core/oqm-core-characteristics/app/UIs.py b/software/core/oqm-core-characteristics/app/UIs.py index e0aefdd62..d3751f04b 100644 --- a/software/core/oqm-core-characteristics/app/UIs.py +++ b/software/core/oqm-core-characteristics/app/UIs.py @@ -89,6 +89,7 @@ def getCategory(self, category: str): class UiUtils: ui_dir = os.getenv('CHARACTERISTICS_UI_DIR', '/data/uis/') ui_cache = None + ui_cache_force_refresh = False @classmethod def __get_ui_endpoints(cls, uiRaw) -> UiEndpoints: @@ -99,12 +100,16 @@ def __get_ui_endpoints(cls, uiRaw) -> UiEndpoints: @classmethod def __get_ui(cls, uiRaw) -> UiCache: + + if "url" not in uiRaw: + cls.ui_cache_force_refresh = True + return UiCache( uiRaw["order"] if "order" in uiRaw else 999, uiRaw["id"] if "id" in uiRaw else None, uiRaw["name"], uiRaw["description"], - uiRaw["url"], + uiRaw["url"] if "url" in uiRaw else "", ImageUtils.get_image( uiRaw["icon"], os.getenv('CHARACTERISTICS_UIS_ICON_DIR', "/") @@ -130,7 +135,7 @@ def validate_ui_list(cls, uiList: list[UiCache]) -> None: @classmethod def get_uis_cache(cls) -> UisCache: - if cls.ui_cache is not None: + if cls.ui_cache is not None and not cls.ui_cache_force_refresh: return cls.ui_cache directory = os.getenv('UIS_DATA_DIR', "/data/uis/") diff --git a/software/core/oqm-core-characteristics/installerSrc/installerProperties.json b/software/core/oqm-core-characteristics/installerSrc/installerProperties.json index 72d05c185..f7d051c07 100644 --- a/software/core/oqm-core-characteristics/installerSrc/installerProperties.json +++ b/software/core/oqm-core-characteristics/installerSrc/installerProperties.json @@ -7,7 +7,7 @@ "description": "Characteristics instance for Open QuarterMaster.", "homepage": "https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/tree/main/software/core/oqm-core-characteristics", "dependencies": { - "deb": "curl, jq, docker.io, oqm-manager-station+captain (>= 2.11.0)", + "deb": "curl, jq, docker.io, oqm-manager-station+captain (>= 2.11.0), oqm-infra-homepage", "debRec": "" }, "copyright": { diff --git a/software/core/oqm-core-characteristics/installerSrc/oqm-core-characteristics.service b/software/core/oqm-core-characteristics/installerSrc/oqm-core-characteristics.service index 90774f29a..7f4ca53b0 100644 --- a/software/core/oqm-core-characteristics/installerSrc/oqm-core-characteristics.service +++ b/software/core/oqm-core-characteristics/installerSrc/oqm-core-characteristics.service @@ -6,7 +6,7 @@ [Unit] Description=Characteristics server for Open Quartermaster. Version ${version}". Documentation=https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/tree/main/software/core -After=docker.service +After=docker.service oqm-infra-homepage.service Wants=network-online.target docker.socket Requires=docker.socket From d5eaafd6714d680d1c57e72603ae6882f7adf767 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Mon, 25 May 2026 00:11:29 -0400 Subject: [PATCH 09/13] Core - Base Station - fixing broken you page after int entity change --- .../resources/templates/webui/pages/you.html | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/software/core/oqm-core-base-station/src/main/resources/templates/webui/pages/you.html b/software/core/oqm-core-base-station/src/main/resources/templates/webui/pages/you.html index a42b60a48..f25318771 100644 --- a/software/core/oqm-core-base-station/src/main/resources/templates/webui/pages/you.html +++ b/software/core/oqm-core-base-station/src/main/resources/templates/webui/pages/you.html @@ -10,25 +10,25 @@
-
Username:
-
{userInfo.getUsername()}
- + {!
Username:
!} + {!
{userInfo.getUsername()}
!} +
Name:
{userInfo.getName()}
- +
Email:
{userInfo.getEmail()}
- +
Roles:
{#for curRole in userInfo.getRoles()} {curRole} {/for}
- +
OQM Id:
{userInfo.getId()}{#copyTextButton /}
- + {!{#if !user.getExternIds().isEmpty()}!} {!
External Ids:
!} {!
!} @@ -40,7 +40,7 @@ {!
!} {!!} {!{/if}!} - + {!{#if !userInfo.getAttributes().isEmpty()}!} {!
Attributes:
!} {!
!} @@ -92,10 +92,10 @@

{/pageScript} -{/include} \ No newline at end of file +{/include} From 1394fe0092cb1e095aadc0e3ec518d51a4a8f1da Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Mon, 25 May 2026 00:12:47 -0400 Subject: [PATCH 10/13] Core - Characteristics - Fixing more possibly broken references --- software/core/oqm-core-characteristics/app/UIs.py | 4 +++- .../installerSrc/installerProperties.json | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/software/core/oqm-core-characteristics/app/UIs.py b/software/core/oqm-core-characteristics/app/UIs.py index d3751f04b..b55ec7fc1 100644 --- a/software/core/oqm-core-characteristics/app/UIs.py +++ b/software/core/oqm-core-characteristics/app/UIs.py @@ -94,7 +94,7 @@ class UiUtils: @classmethod def __get_ui_endpoints(cls, uiRaw) -> UiEndpoints: return UiEndpoints( - uiRaw["monitorEndpoint"], + uiRaw["monitorEndpoint"] if "monitorEndpoint" in uiRaw else None, uiRaw["item"] if "item" in uiRaw else None, ) @@ -138,6 +138,8 @@ def get_uis_cache(cls) -> UisCache: if cls.ui_cache is not None and not cls.ui_cache_force_refresh: return cls.ui_cache + cls.ui_cache_force_refresh = False + directory = os.getenv('UIS_DATA_DIR', "/data/uis/") uisRawData: list[dict] = list() diff --git a/software/core/oqm-core-characteristics/installerSrc/installerProperties.json b/software/core/oqm-core-characteristics/installerSrc/installerProperties.json index be1050297..2d553f793 100644 --- a/software/core/oqm-core-characteristics/installerSrc/installerProperties.json +++ b/software/core/oqm-core-characteristics/installerSrc/installerProperties.json @@ -1,6 +1,6 @@ { "packageName": "oqm-core-characteristics", - "version": "1.1.0", + "version": "1.1.1-SNAPSHOT", "maintainer": { "name": "EBP " }, From 0ebea13b2a9348d6542253b85c9e5b4e31ee5e94 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Mon, 25 May 2026 00:13:25 -0400 Subject: [PATCH 11/13] SNH Tests - Added characteristics to services being run with tests --- .../snhConnector/SnhConnector.java | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/deployment/Single Host/tests/src/test/java/stationCaptainTest/testResources/snhConnector/SnhConnector.java b/deployment/Single Host/tests/src/test/java/stationCaptainTest/testResources/snhConnector/SnhConnector.java index a04917540..cc2511717 100644 --- a/deployment/Single Host/tests/src/test/java/stationCaptainTest/testResources/snhConnector/SnhConnector.java +++ b/deployment/Single Host/tests/src/test/java/stationCaptainTest/testResources/snhConnector/SnhConnector.java @@ -39,7 +39,7 @@ @JsonSubTypes.Type(value = ExistingSnhSetupConfig.class, name = "EXISTING"), }) public abstract class SnhConnector implements Closeable { - + protected C getSetupConfig() { try { //noinspection unchecked @@ -49,20 +49,20 @@ protected C getSetupConfig() { throw new RuntimeException("FAILED to cast config as appropriate.", e); } } - + public void init(boolean install) { this.setupForInstall(); if (install) { this.installOqm(true); } } - + public abstract SnhType getType(); - + public abstract CommandResult runCommand(String... command); - + public abstract void copyToHost(String destination, InputStream input); - + public void copyToHost(String remoteFile, File source) { try( FileInputStream is = new FileInputStream(source); @@ -72,20 +72,20 @@ public void copyToHost(String remoteFile, File source) { throw new RuntimeException(e); } } - + public void copyToHost(String destinationDir, Collection localFiles) { log.info("Copying files to host into {}: {}", destinationDir, (Object) localFiles); for (File curFile : localFiles) { this.copyToHost(destinationDir + curFile.getName(), curFile); } } - + public void copyToHost(String destinationDir, File... localFiles) { this.copyToHost(destinationDir, localFiles); } - + public abstract void copyFromHost(String remoteFile, OutputStream destination); - + public void copyFromHost(String remoteFile, File destination) { try( FileOutputStream os = new FileOutputStream(destination); @@ -95,14 +95,14 @@ public void copyFromHost(String remoteFile, File destination) { throw new RuntimeException(e); } } - - + + public void setupForInstall() { switch (this.getSetupConfig().getInstallTypeConfig().getType()){ case REPO -> { log.info("Setting up host for repo install."); RepoInstallTypeConfig config = (RepoInstallTypeConfig) this.getSetupConfig().getInstallTypeConfig(); - + String setupUrl = "https://deployment.openquartermaster.com/repos/"+config.getRepoBranch()+"/"+config.getInstallerType().name()+"/setup-repo.sh"; log.debug("Setup script url: {}", setupUrl); CommandResult result = this.runCommand("wget", "-q", "-O", "/tmp/repoSetup.sh", setupUrl); @@ -123,8 +123,9 @@ public void setupForInstall() { log.info("Building installers."); CommandResult.from(new ProcessBuilder("../Station-Captain/makeInstallers.sh")).assertSuccess("Build Station Captain Installers"); CommandResult.from(new ProcessBuilder("../Infrastructure/makeInstallers.sh")).assertSuccess("Build Infrastructure Installers"); - CommandResult.from(new ProcessBuilder("../../../software/core/oqm-core-api/makeInstallers.sh")).assertSuccess("Build Base Station Installers"); + CommandResult.from(new ProcessBuilder("../../../software/core/oqm-core-api/makeInstallers.sh")).assertSuccess("Build Core API Installers"); CommandResult.from(new ProcessBuilder("../../../software/core/oqm-core-base-station/makeInstallers.sh")).assertSuccess("Build Base Station Installers"); + CommandResult.from(new ProcessBuilder("../../../software/core/oqm-core-characteristics/makeInstallers.sh")).assertSuccess("Build Characteristics Installers"); CommandResult.from(new ProcessBuilder("../../../software/plugins/external-item-search/makeInstallers.sh")).assertSuccess("Build External Item Search Installers"); log.info("Done building installers."); } catch(IOException | InterruptedException e) { @@ -134,23 +135,24 @@ public void setupForInstall() { installers.addAll(List.of(new File("../Station-Captain/bin/").listFiles((FileFilter) new WildcardFileFilter("oqm-*."+ this.getSetupConfig().getInstallTypeConfig().getInstallerType().name())))); installers.addAll(List.of(new File("../Infrastructure/build/").listFiles((FileFilter) new WildcardFileFilter("oqm-*."+ this.getSetupConfig().getInstallTypeConfig().getInstallerType().name())))); installers.addAll(List.of(new File("../../../software/core/oqm-core-api/build/installers/").listFiles((FileFilter) new WildcardFileFilter("oqm-*."+ this.getSetupConfig().getInstallTypeConfig().getInstallerType().name())))); + installers.addAll(List.of(new File("../../../software/core/oqm-core-characteristics/build/installers/").listFiles((FileFilter) new WildcardFileFilter("oqm-*."+ this.getSetupConfig().getInstallTypeConfig().getInstallerType().name())))); installers.addAll(List.of(new File("../../../software/core/oqm-core-base-station/build/installers/").listFiles((FileFilter) new WildcardFileFilter("oqm-*."+ this.getSetupConfig().getInstallTypeConfig().getInstallerType().name())))); installers.addAll(List.of(new File("../../../software/plugins/external-item-search/build/installers/").listFiles((FileFilter) new WildcardFileFilter("oqm-*."+ this.getSetupConfig().getInstallTypeConfig().getInstallerType().name())))); log.info("Installers to add to host: {}", installers); - + this.runCommand("mkdir", "-p", "/tmp/oqm-installers/").assertSuccess("List uploaded installers."); this.runCommand("rm", "-rf", "/tmp/oqm-installers/*").assertSuccess("Remove previously uploaded installers."); this.runCommand("chmod", "777", "/tmp/oqm-installers").assertSuccess("Adjust permissions of installer upload dir."); log.info("Prepared destination directory."); this.copyToHost("/tmp/oqm-installers/", installers); log.info("Copied all files to host."); - + CommandResult result = this.runCommand("ls", "/tmp/oqm-installers/").assertSuccess("List uploaded installers."); log.info("Installers on remote box: {}", result.getStdOut()); } } } - + public CommandResult installOqm(boolean verify) { CommandResult output = null; switch (this.getSetupConfig().getInstallTypeConfig().getInstallerType()) { @@ -176,7 +178,7 @@ public CommandResult installOqm(boolean verify) { } return output; } - + public void uninstallOqm(){ log.info("Uninstalling OQM"); switch (this.getSetupConfig().getInstallTypeConfig().getInstallerType()){ @@ -194,12 +196,12 @@ public void uninstallOqm(){ } this .runCommand("rm", "-rf", "/etc/oqm", "/tmp/oqm", "/data/oqm").assertSuccess("Remove OQM directories"); } - - + + @Override public void close() throws IOException { } - + public static SnhConnector fromConfig() throws IOException { switch (ConfigReader.getTestRunConfig().getSetupConfig().getType()){ case EXISTING -> { From da1ce7b695af24a6a206ab9edfdd619ac8991af9 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Mon, 25 May 2026 00:21:04 -0400 Subject: [PATCH 12/13] Core - API - typos in docs --- .../oqm-core-api/docs/sphinx-test/source/design_decisions.rst | 2 +- .../oqm-core-api/docs/sphinx-test/source/features/index.rst | 2 +- .../core/oqm-core-api/docs/sphinx-test/source/usage/index.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst index 44cfb273a..e73715a85 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/design_decisions.rst @@ -37,5 +37,5 @@ Optionality Functional / Design Decisions (major) ===================================== -This section goes over why we implemented certain high level functionalities they way we did. +This section goes over why we implemented certain high level functionalities the way we did. We won't go too deep into every tiny design choice, but will talk to higher level design patterns. diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst index 243e8b270..64e96cf7f 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/features/index.rst @@ -6,7 +6,7 @@ This is a comprehensive set of requirements to describe high level capabilities Intended as a traceable, authoritative itemization of requirements to trace functionalities, code, tests, and documentation back to. Is NOT a low level implementation detailed document, rather a higher level set of generalized capabilities, requirements, and features. -This mean that things like specific data models, implementation details, and similar low level information is not here. +This means that things like specific data models, implementation details, and similar low level information is not here. .. toctree:: :numbered: diff --git a/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst b/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst index 03b6ffc0b..19cbde9fa 100644 --- a/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst +++ b/software/core/oqm-core-api/docs/sphinx-test/source/usage/index.rst @@ -1,7 +1,7 @@ Usage / User Guide ##################### -This section is concerned with how actually use the service. +This section is concerned with how to actually use the service. .. toctree:: From 37a0b53e0bf1a1c3cf510efe4fe17f69260276a5 Mon Sep 17 00:00:00 2001 From: GregJohnStewart Date: Mon, 25 May 2026 00:21:29 -0400 Subject: [PATCH 13/13] typos in docs --- docs/sphinx/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index afa52eb8f..7d05e80de 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -13,7 +13,7 @@ Open QuarterMaster Documentation Welcome to the Open QuarterMaster docs! This site is a comprehensive look at everything Open QuarterMaster! -Open Quartermaster is an open source inventory management system, designed to be simple to use yet powerful and extendable. The last inventory management system you will ever need! +Open QuarterMaster is an open source inventory management system, designed to be simple to use yet powerful and extendable. The last inventory management system you will ever need! Quick Links -----------