From 2c21a87b0f9e77dae4d671d86b2fd8f67cb8019b Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 2 Feb 2021 09:48:59 -0800 Subject: [PATCH 01/26] Convert quickstart to rst --- docs/conf.py | 2 +- docs/deployment.rst | 3 +++ docs/installation.rst | 10 ++++++++++ docs/overview.rst | 7 +++++++ docs/quickstart.rst | 29 +++++++++++++++++++++++++++++ 5 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 docs/deployment.rst create mode 100644 docs/installation.rst create mode 100644 docs/overview.rst create mode 100644 docs/quickstart.rst diff --git a/docs/conf.py b/docs/conf.py index 6d82dad5b..ad7066eee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -50,7 +50,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/deployment.rst b/docs/deployment.rst new file mode 100644 index 000000000..681695c44 --- /dev/null +++ b/docs/deployment.rst @@ -0,0 +1,3 @@ +============ +Deployment +============ \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 000000000..f89a79802 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,10 @@ +============ +Installation +============ + +The MMS, in it's default configuration currently has two main dependencies: + - Relational Database (e.g. Postgresql, MySQL, etc.) + - Document Store (e.g. Elasticsearch) + +For artifact storage, an S3 compliant object store is necessary. We develop against MinIO and deploy against AWS S3, however, any S3 compliant object store will suffice. + diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 000000000..8d0cfc296 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,7 @@ +============ +Overview +============ + +The Model Management System (MMS) provide services for managing models and is a version control system for structured data. It exposes model information through RESTful web services that can be used for CRUD operations, branching, and tagging of the model repository. This heart of the MMS is the View Service which supports the transclusion features of Views. + +The MMS also provides web services for storing and searching Jupyter Lab notebooks. \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 000000000..17443d1a0 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,29 @@ +============ +Quick Start +============ + +Test Setup +========== + +Dependencies +------------ + Docker + We suggest using Docker to set up PostgreSQL and Elasticsearch. Installation instructions are found here: `Docker documentation `_ + + Java SE Development Kit 11+ + Installation instructions: `JDK-11 download `_ + + Postgresql + Install postgres (PostgreSQL) 11, instructions for Docker: `PostgreSQL with Docker `_ + `docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 postgres:11-alpine` + + or Mysql 5.7 `Mysql with Docker `_ + `docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 mysql:5.7` + + Elasticsearch + Install Elasticsearch 7.8. If you use Docker instructions are available here: `Setting up Elasticsearch with Docker `_ + `docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.8.1` + + MinIO + Install MinIO for artifact storage. `Instructions for MinIO `_ + `docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" minio/minio server /data` From 7ba9249059a1907bf6cf885196abf598c3afa2ba Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 2 Feb 2021 14:47:43 -0800 Subject: [PATCH 02/26] Add basic docs to toctree --- docs/index.rst | 4 ++++ docs/quickstart.rst | 11 ++++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index d970a0356..f70f0daf0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,10 @@ Welcome to Model Management System's documentation! .. toctree:: :maxdepth: 2 :caption: Contents: + overview + quickstart + installation + deployment diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 17443d1a0..7276b4470 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -13,11 +13,10 @@ Dependencies Java SE Development Kit 11+ Installation instructions: `JDK-11 download `_ - Postgresql + Postgresql or Mysql 5.7 Install postgres (PostgreSQL) 11, instructions for Docker: `PostgreSQL with Docker `_ `docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 postgres:11-alpine` - - or Mysql 5.7 `Mysql with Docker `_ + Or mysql: `Mysql with Docker `_ `docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 mysql:5.7` Elasticsearch @@ -27,3 +26,9 @@ Dependencies MinIO Install MinIO for artifact storage. `Instructions for MinIO `_ `docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" minio/minio server /data` + +MMS Application +--------------- + MMS + Install MMS and run the web server: + `` \ No newline at end of file From f5b6d06ad1755968dcb80263047a16d69aa7a179 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 2 Feb 2021 15:18:54 -0800 Subject: [PATCH 03/26] Complete initial quick start document --- docs/_templates/layout.html | 5 +++++ docs/quickstart.rst | 43 ++++++++++++++++++++++++++++--------- 2 files changed, 38 insertions(+), 10 deletions(-) create mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 000000000..d635d550b --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,5 @@ +{% extends "!layout.html" %} + +{% block menu %} +{{ super() }} +{% endblock %} \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 7276b4470..bbd5f28cc 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -6,7 +6,7 @@ Test Setup ========== Dependencies ------------- +************ Docker We suggest using Docker to set up PostgreSQL and Elasticsearch. Installation instructions are found here: `Docker documentation `_ @@ -15,20 +15,43 @@ Dependencies Postgresql or Mysql 5.7 Install postgres (PostgreSQL) 11, instructions for Docker: `PostgreSQL with Docker `_ - `docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 postgres:11-alpine` + :: + `docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 --name=postgres postgres:11-alpine` Or mysql: `Mysql with Docker `_ - `docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 mysql:5.7` + :: + `docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 --name=mysql mysql:5.7` Elasticsearch Install Elasticsearch 7.8. If you use Docker instructions are available here: `Setting up Elasticsearch with Docker `_ - `docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.8.1` + :: + `docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" --name=elasticsearch docker.elastic.co/elasticsearch/elasticsearch:7.8.1` MinIO Install MinIO for artifact storage. `Instructions for MinIO `_ - `docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" minio/minio server /data` + :: + `docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" --name=minio minio/minio server /data` -MMS Application ---------------- - MMS - Install MMS and run the web server: - `` \ No newline at end of file +Running MMS +*********** + Configure the application. + Each module of MMS can define configuration properties required to function. These properties can be defined in a single location, by default, called application.properties. Place application.properties in the classpath for MMS to use the defined values. For an example, see `example application.properties `_ + Alternatively, the properties file can be given by defining the environment variable `SPRING_CONFIG_LOCATION`. + + Run the application. + First, create a container from an MMS image. In the example below, the container is using the host network for simplicity. + :: + `docker create --name=mms --network="host" -e "SPRING_CONFIG_LOCATION=/mms.properties" openmbee/mms:4.0.0-b5` + + Copy over custom properties. + If using the above command, copy the properties file to the defined spring config location. + :: + `docker cp mms.properties mms:/mms.properties` + + Start the container. + Finally, start the container with the injected properties file. + :: + `docker start mms` + +More Information +**************** + For more information and hints, check the `docker-compose.yml `_ in the project root to see how we stand up an instance for testing purposes. \ No newline at end of file From 1db1ff38eefb268ecc6003c6d61f9a8ecf49bd4b Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 2 Feb 2021 16:17:46 -0800 Subject: [PATCH 04/26] Add content on index --- docs/conf.py | 4 ++++ docs/index.rst | 4 ++++ docs/quickstart.rst | 3 --- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ad7066eee..1f14aad99 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,6 +52,10 @@ # html_theme = 'default' +html_theme_options = { + "rightsidebar": "true" +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/index.rst b/docs/index.rst index f70f0daf0..bc9f29896 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,6 +6,10 @@ Welcome to Model Management System's documentation! =================================================== +The Model Management System (MMS) provide services for managing models and is a version control system for structured data. It exposes model information through RESTful web services that can be used for CRUD operations, branching, and tagging of the model repository. This heart of the MMS is the View Service which supports the transclusion features of Views. + +The MMS also provides web services for storing and searching Jupyter Lab notebooks. + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/docs/quickstart.rst b/docs/quickstart.rst index bbd5f28cc..968e9fa2c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -2,9 +2,6 @@ Quick Start ============ -Test Setup -========== - Dependencies ************ Docker From ddecc5ed15d5c1ac023b55bdda60d274adff322e Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 2 Feb 2021 16:23:04 -0800 Subject: [PATCH 05/26] Use rtd theme --- docs/conf.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1f14aad99..98552a8f6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,6 +12,7 @@ # import os import sys +import sphinx_rtd_theme sys.path.insert(0, os.path.abspath('../..')) sys.setrecursionlimit(1500) @@ -34,6 +35,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "sphinx_rtd_theme" ] # Add any paths that contain templates here, relative to this directory. @@ -50,10 +52,22 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' html_theme_options = { - "rightsidebar": "true" + 'analytics_id': '', + 'analytics_anonymize_ip': False, + 'logo_only': False, + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + 'vcs_pageview_mode': '', + 'style_nav_header_background': 'white', + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False } # Add any paths that contain custom static files (such as style sheets) here, From cd774c5fd67e9625d02a2304b6f154079793e48a Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 15:58:39 -0800 Subject: [PATCH 06/26] Add module pages and fix TOC. --- docs/Makefile | 2 +- docs/_templates/layout.html | 5 --- docs/conf.py | 13 +++++--- docs/deployment.rst | 17 ++++++++-- docs/index.rst | 25 ++++++--------- docs/installation.rst | 9 +++--- docs/modules/artifacts.rst | 6 ++++ docs/modules/authenticator.rst | 6 ++++ docs/modules/cameo.rst | 6 ++++ docs/modules/core.rst | 6 ++++ docs/modules/crud.rst | 6 ++++ docs/modules/data.rst | 6 ++++ docs/modules/elastic.rst | 43 +++++++++++++++++++++++++ docs/modules/index.rst | 13 ++++++++ docs/modules/json.rst | 6 ++++ docs/modules/jupyter.rst | 6 ++++ docs/modules/ldap.rst | 39 +++++++++++++++++++++++ docs/modules/localuser.rst | 15 +++++++++ docs/modules/permissions.rst | 6 ++++ docs/modules/rdb.rst | 49 ++++++++++++++++++++++++++++ docs/modules/search.rst | 6 ++++ docs/modules/storage.rst | 22 +++++++++++++ docs/modules/twc.rst | 58 ++++++++++++++++++++++++++++++++++ docs/modules/webhooks.rst | 6 ++++ docs/overview.rst | 9 ++++-- docs/quickstart.rst | 23 ++++++++++---- 26 files changed, 368 insertions(+), 40 deletions(-) delete mode 100644 docs/_templates/layout.html create mode 100644 docs/modules/artifacts.rst create mode 100644 docs/modules/authenticator.rst create mode 100644 docs/modules/cameo.rst create mode 100644 docs/modules/core.rst create mode 100644 docs/modules/crud.rst create mode 100644 docs/modules/data.rst create mode 100644 docs/modules/elastic.rst create mode 100644 docs/modules/index.rst create mode 100644 docs/modules/json.rst create mode 100644 docs/modules/jupyter.rst create mode 100644 docs/modules/ldap.rst create mode 100644 docs/modules/localuser.rst create mode 100644 docs/modules/permissions.rst create mode 100644 docs/modules/rdb.rst create mode 100644 docs/modules/search.rst create mode 100644 docs/modules/storage.rst create mode 100644 docs/modules/twc.rst create mode 100644 docs/modules/webhooks.rst diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb9..c7c069650 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . +SOURCEDIR = src BUILDDIR = _build # Put it first so that "make" without argument is like "make help". diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index d635d550b..000000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "!layout.html" %} - -{% block menu %} -{{ super() }} -{% endblock %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 98552a8f6..5dc70d24a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ # import os import sys -import sphinx_rtd_theme + sys.path.insert(0, os.path.abspath('../..')) sys.setrecursionlimit(1500) @@ -35,7 +35,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "sphinx_rtd_theme" + 'sphinx_rtd_theme', ] # Add any paths that contain templates here, relative to this directory. @@ -56,12 +56,10 @@ html_theme_options = { 'analytics_id': '', - 'analytics_anonymize_ip': False, 'logo_only': False, 'display_version': True, 'prev_next_buttons_location': 'bottom', 'style_external_links': False, - 'vcs_pageview_mode': '', 'style_nav_header_background': 'white', 'collapse_navigation': True, 'sticky_navigation': True, @@ -70,6 +68,13 @@ 'titles_only': False } +html_sidebars = { + '**': ['globaltoc.html', + 'relations.html', + 'sourcelink.html', + 'searchbox.html'] +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/deployment.rst b/docs/deployment.rst index 681695c44..71ebe20d2 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -1,3 +1,16 @@ -============ +.. _deployment: + Deployment -============ \ No newline at end of file +============ + +Bare Metal +********** +:: + + java -jar mms-4.0.0.jar + +Docker +****** +:: + + docker run mms diff --git a/docs/index.rst b/docs/index.rst index bc9f29896..bd8574c6f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,7 @@ sphinx-quickstart on Tue Oct 20 07:03:26 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _index: Welcome to Model Management System's documentation! =================================================== @@ -11,18 +12,12 @@ The Model Management System (MMS) provide services for managing models and is a The MMS also provides web services for storing and searching Jupyter Lab notebooks. .. toctree:: - :maxdepth: 2 - :caption: Contents: - overview - quickstart - installation - deployment - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + :maxdepth: 2 + :caption: Table of Contents + :glob: + + overview + quickstart + installation + deployment + modules/index \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst index f89a79802..b02c88209 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,10 +1,11 @@ -============ +.. _installation: + Installation ============ -The MMS, in it's default configuration currently has two main dependencies: +The MMS, in it's reference implementation configuration currently has two main dependencies\: + - Relational Database (e.g. Postgresql, MySQL, etc.) - Document Store (e.g. Elasticsearch) - -For artifact storage, an S3 compliant object store is necessary. We develop against MinIO and deploy against AWS S3, however, any S3 compliant object store will suffice. + - Optionally, for artifact storage, an S3 compliant object store is necessary. We develop against MinIO and deploy against AWS S3, however, any S3 compliant object store will suffice. (e.g. MinIO) diff --git a/docs/modules/artifacts.rst b/docs/modules/artifacts.rst new file mode 100644 index 000000000..b35c7392c --- /dev/null +++ b/docs/modules/artifacts.rst @@ -0,0 +1,6 @@ +.. _artifacts: + +Artifacts +========= + +Artifacts is an interface to implement for artifact object support. See :ref:`storage`. for the default implementation. diff --git a/docs/modules/authenticator.rst b/docs/modules/authenticator.rst new file mode 100644 index 000000000..12830f2ba --- /dev/null +++ b/docs/modules/authenticator.rst @@ -0,0 +1,6 @@ +.. _authenticator: + +Authenticator +============= + +Authenticator is an interface to implement for authentication. See :ref:`localuser`. or :ref:`ldap`. for implementations. \ No newline at end of file diff --git a/docs/modules/cameo.rst b/docs/modules/cameo.rst new file mode 100644 index 000000000..a4e48cc4b --- /dev/null +++ b/docs/modules/cameo.rst @@ -0,0 +1,6 @@ +.. _cameo: + +Cameo +===== + +The Cameo Module adds compatibility for the Cameo Development Kit. \ No newline at end of file diff --git a/docs/modules/core.rst b/docs/modules/core.rst new file mode 100644 index 000000000..6969d3d94 --- /dev/null +++ b/docs/modules/core.rst @@ -0,0 +1,6 @@ +.. _core: + +Core +==== + +The Core module provides essential classes and helpers for the MMS. \ No newline at end of file diff --git a/docs/modules/crud.rst b/docs/modules/crud.rst new file mode 100644 index 000000000..774313f65 --- /dev/null +++ b/docs/modules/crud.rst @@ -0,0 +1,6 @@ +.. _crud: + +CRUD +==== + +The CRUD Module provides default Create, Read, Update, Delete functionality to the MMS. \ No newline at end of file diff --git a/docs/modules/data.rst b/docs/modules/data.rst new file mode 100644 index 000000000..15c4a1de8 --- /dev/null +++ b/docs/modules/data.rst @@ -0,0 +1,6 @@ +.. _data: + +Data +==== + +The Data Module provides data objects for core MMS functionality. \ No newline at end of file diff --git a/docs/modules/elastic.rst b/docs/modules/elastic.rst new file mode 100644 index 000000000..c757b67a7 --- /dev/null +++ b/docs/modules/elastic.rst @@ -0,0 +1,43 @@ +.. _elastic: + +Elastic +======= + +The Elastic Module implements the NodeIndex interface from the crud module. + +Configuration +************* + +The following are a list of options to configure the Elastic Module for MMS. + + elasticsearch.host + The host name of the Elasticsearch server or cluster. Required. + + elasticsearch.port + The port number of the Elasticsearch server or cluster. Required. + + elasticsearch.http + The transport protocol to use to connect to the Elasticsearch server or cluster. Required. + + elasticsearch.limit.result + The maximum number of results a single search request should return. Optional. Default: 10000 + + elasticsearch.limit.term=1000 + The maximum number of terms that a search query should contain. Optional. Default: 1000 + + elasticsearch.limit.scrollTimeout + The maximum time to wait for search requests. Optional. Default: 1000 + + elasticsearch.limit.get + The maximum number of elements that a single get request should return. Optional. Default: 5000 + + elasticsearch.limit.index + The maximum number of elements that will be indexed in a single bulk request. Optional. Default: 5000 + + elasticsearch.limit.commit + The maximum number of elements to limit commit objects to. Set this to a reasonable size in order to avoid object size limitations in Elasticsearch. + +Elastic Mappings +**************** + +Elastic mappings are necessary to index fields correctly in Elasticsearch. These mappings are available `here `_. \ No newline at end of file diff --git a/docs/modules/index.rst b/docs/modules/index.rst new file mode 100644 index 000000000..ff415c5b1 --- /dev/null +++ b/docs/modules/index.rst @@ -0,0 +1,13 @@ +.. _modules: + +Modules +======= + +This section is for the individual modules currently available for MMS. + +.. toctree:: + :maxdepth: 2 + :caption: Modules + :glob: + + * \ No newline at end of file diff --git a/docs/modules/json.rst b/docs/modules/json.rst new file mode 100644 index 000000000..77bcc11a3 --- /dev/null +++ b/docs/modules/json.rst @@ -0,0 +1,6 @@ +.. _json: + +JSON +==== + +The JSON Module provides data objects for marshalling JSON to and from Java POJOs \ No newline at end of file diff --git a/docs/modules/jupyter.rst b/docs/modules/jupyter.rst new file mode 100644 index 000000000..414acf9c7 --- /dev/null +++ b/docs/modules/jupyter.rst @@ -0,0 +1,6 @@ +.. _jupyter: + +Jupyter +======= + +The Jupyter module adds the ability to support jupyter notebooks. \ No newline at end of file diff --git a/docs/modules/ldap.rst b/docs/modules/ldap.rst new file mode 100644 index 000000000..07c99c311 --- /dev/null +++ b/docs/modules/ldap.rst @@ -0,0 +1,39 @@ +.. _ldap: + +LDAP +==== + +The LDAP Module provides the ability to authenticate users from an LDAP Identity provider. + +Configuration +************* + + ldap.provider.base + The base string to use. Required. + + ldap.provider.url + The provider url, including the base. Required. + + ldap.provider.userdn + The userdn to use to authenticate to the provider. Optional. + + ldap.provider.password + The password to use to authenticate to the provider. Optional. + + ldap.user.dn.pattern + The dn pattern for the user. Required. + + ldap.user.attributes.username + The attribute to use for the username. Optional. Default: uid + + ldap.user.attributes.email + The attribute to use for the email address. Optional. Default: mail + + ldap.group.role.attribute + The attribute to use for the group role. Optional. + + ldap.group.search.base + The base for group search. Optional. + + ldap.group.search.filter + The search filter for group search. Optional. diff --git a/docs/modules/localuser.rst b/docs/modules/localuser.rst new file mode 100644 index 000000000..815438519 --- /dev/null +++ b/docs/modules/localuser.rst @@ -0,0 +1,15 @@ +.. _localuser: + +Localuser +========= + +The LocalUser module provides the ability to authenticate users in the common database. Currently, the main functionality is to set a local admin user during initialization. + +Configuration +************* + + mms.admin.username + The root admin username to use. + + mms.admin.password + The root admin password to use. \ No newline at end of file diff --git a/docs/modules/permissions.rst b/docs/modules/permissions.rst new file mode 100644 index 000000000..943f97a2c --- /dev/null +++ b/docs/modules/permissions.rst @@ -0,0 +1,6 @@ +.. _permissions: + +Permissions +=========== + +The Permissions Module provides permissions to MMS. \ No newline at end of file diff --git a/docs/modules/rdb.rst b/docs/modules/rdb.rst new file mode 100644 index 000000000..01ff5b00d --- /dev/null +++ b/docs/modules/rdb.rst @@ -0,0 +1,49 @@ +.. _rdb: + +RDB +=== + +The RDB Module implements the JPA Repositories defined in the CRUD Module. + +Configuration +************* + +The following are a list of options to configure the RDB Module for MMS. + + spring.datasource.url + The datasource url in jdbc format. Required. + + spring.datasource.database + The database name to use for global MMS configuration. Required. + + spring.datasource.username + The username to use for authentication. Optional. + + spring.datasource.password + The password to use for authentication. Optional. + + spring.datasource.driver-class-name + The driver to use for JDBC. Any database driver supported by Spring Data can be used. Required. + + spring.datasource.initialization-mode + The initialization mode to use when starting the MMS application. Accepted values are `always`, `embedded`, and `never`. Required. + + spring.jpa.properties.hibernate.dialect + The hibernate dialect to use. Required. + + spring.jpa.properties.hibernate.dialect.storage_engine + The storage engine to use. Optional. + + spring.jpa.hibernate.ddl-auto + The DDL generation option. Accepted values are `none`, `create`, `create-drop`, `validate`, and `update` Required. + +Required Properties +******************* + +These properties are required for the MMS application to provide all available features. They are set by default, but are listed here for completeness. + + :: + + `spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true` + `spring.jpa.open-in-view=false` + `spring.main.allow-bean-definition-overriding=true` \ No newline at end of file diff --git a/docs/modules/search.rst b/docs/modules/search.rst new file mode 100644 index 000000000..6df37dfa3 --- /dev/null +++ b/docs/modules/search.rst @@ -0,0 +1,6 @@ +.. _mmssearch: + +Search +====== + +The Search Module \ No newline at end of file diff --git a/docs/modules/storage.rst b/docs/modules/storage.rst new file mode 100644 index 000000000..f7c223513 --- /dev/null +++ b/docs/modules/storage.rst @@ -0,0 +1,22 @@ +.. _storage: + +Storage +======= + +Storage is the default implementation of the Artifact interface. It is compatible with S3 compliant APIs. + +Configuration +************* + + s3.access_key + This is the access key for the S3 bucket. Required. + + s3.secret_key + This is the secret key for the S3 bucket. Required. + + s3.region + This is the region that the S3 bucket is located in. Required. + + s3.bucket + This is the name of the S3 bucket. Optional. + `Default: mms` \ No newline at end of file diff --git a/docs/modules/twc.rst b/docs/modules/twc.rst new file mode 100644 index 000000000..337948254 --- /dev/null +++ b/docs/modules/twc.rst @@ -0,0 +1,58 @@ +.. _twc: + +TWC +=== + +The TWC Module provides integration with NoMagic's Teamwork Cloud. + +Configuration +************* +The TWC Module support multiple instances of TWC. The following configuration are available, where twc.instances is a list. + + twc.instances[i].url + The url of the ReST interface of TWC. + + twc.instances[i].protocol + The protocol to use for the ReST interface of TWC. + + twc.instances[i].port + The port for the ReST interface of TWC. + + twc.instances[i].aliases + A list of aliases for the ReST interface of TWC. + + twc.instances[i].adminUsername + The admin username to use with the defined instance. Required. + + twc.instances[i].adminPwd + The admin password to use with the defined instance. Required. + + twc.instances[i].roles.project_read + The TWC roles to use for MMS project_read permissions. + + twc.instances[i].roles.project_read_commits + The TWC roles to use for MMS project_read_commits permissions. + + twc.instances[i].roles.project_read_permissions + The TWC roles to use for MMS project_read_permissions permissions. + + twc.instances[i].roles.project_edit + The TWC roles to use for MMS project_edit permissions. + + twc.instances[i].roles.project_create_branch + The TWC roles to use for MMS project_create_branch permissions. + + twc.instances[i].roles.project_update_permissions + The TWC roles to use for MMS project_update_permissions permissions. + + twc.instances[i].roles.branch_read + The TWC roles to use for MMS branch_read permissions. + + twc.instances[i].roles.branch_read_permissions + The TWC roles to use for MMS branch_read_permissions permissions. + + twc.instances[i].roles.branch_edit_content + The TWC roles to use for MMS branch_edit_content permissions. + + twc.instances[i].roles.branch_update_permissions + The TWC roles to use for MMS branch_update_permissions permissions. \ No newline at end of file diff --git a/docs/modules/webhooks.rst b/docs/modules/webhooks.rst new file mode 100644 index 000000000..6ae0c02a2 --- /dev/null +++ b/docs/modules/webhooks.rst @@ -0,0 +1,6 @@ +.. _webhooks: + +Webhooks +======== + +The Webhooks Module provides webhook support for event driven notifications. \ No newline at end of file diff --git a/docs/overview.rst b/docs/overview.rst index 8d0cfc296..0f6e4612c 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,7 +1,10 @@ -============ +.. _overview: + Overview -============ +======== The Model Management System (MMS) provide services for managing models and is a version control system for structured data. It exposes model information through RESTful web services that can be used for CRUD operations, branching, and tagging of the model repository. This heart of the MMS is the View Service which supports the transclusion features of Views. -The MMS also provides web services for storing and searching Jupyter Lab notebooks. \ No newline at end of file +The MMS also provides web services for storing and searching Jupyter Lab notebooks. + +Those looking to use MMS as an end user or in a production environment should look into the `MMS Reference Implementation `_. \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 968e9fa2c..594f9591d 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,52 +1,63 @@ -============ +.. _quickstart: + Quick Start ============ +This quick start will focus on running all dependencies and the MMS application as docker containers. This is most suitable for testing environments. For production deployments, we recommend the `MMS Reference Implementation `_ as a starting point. + Dependencies ************ Docker We suggest using Docker to set up PostgreSQL and Elasticsearch. Installation instructions are found here: `Docker documentation `_ Java SE Development Kit 11+ - Installation instructions: `JDK-11 download `_ + Installation instructions: `JDK-11 download `_ Postgresql or Mysql 5.7 Install postgres (PostgreSQL) 11, instructions for Docker: `PostgreSQL with Docker `_ :: + `docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 --name=postgres postgres:11-alpine` + Or mysql: `Mysql with Docker `_ :: + `docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 --name=mysql mysql:5.7` Elasticsearch Install Elasticsearch 7.8. If you use Docker instructions are available here: `Setting up Elasticsearch with Docker `_ :: + `docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" --name=elasticsearch docker.elastic.co/elasticsearch/elasticsearch:7.8.1` MinIO Install MinIO for artifact storage. `Instructions for MinIO `_ :: + `docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" --name=minio minio/minio server /data` Running MMS *********** - Configure the application. + Configure the application Each module of MMS can define configuration properties required to function. These properties can be defined in a single location, by default, called application.properties. Place application.properties in the classpath for MMS to use the defined values. For an example, see `example application.properties `_ Alternatively, the properties file can be given by defining the environment variable `SPRING_CONFIG_LOCATION`. - Run the application. + Run the application First, create a container from an MMS image. In the example below, the container is using the host network for simplicity. :: + `docker create --name=mms --network="host" -e "SPRING_CONFIG_LOCATION=/mms.properties" openmbee/mms:4.0.0-b5` - Copy over custom properties. + Copy properties If using the above command, copy the properties file to the defined spring config location. :: + `docker cp mms.properties mms:/mms.properties` - Start the container. + Start the container Finally, start the container with the injected properties file. :: + `docker start mms` More Information From 68524e16c4ab46a8aefed567c554ce0a97aa2df9 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:08:55 -0800 Subject: [PATCH 07/26] Minor formatting --- docs/conf.py | 24 +----------------------- docs/modules/elastic.rst | 18 ++++++++++++------ docs/modules/ldap.rst | 6 ++++-- docs/quickstart.rst | 14 +++++++------- 4 files changed, 24 insertions(+), 38 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5dc70d24a..f705791fa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,7 +35,6 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx_rtd_theme', ] # Add any paths that contain templates here, relative to this directory. @@ -52,28 +51,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' - -html_theme_options = { - 'analytics_id': '', - 'logo_only': False, - 'display_version': True, - 'prev_next_buttons_location': 'bottom', - 'style_external_links': False, - 'style_nav_header_background': 'white', - 'collapse_navigation': True, - 'sticky_navigation': True, - 'navigation_depth': 4, - 'includehidden': True, - 'titles_only': False -} - -html_sidebars = { - '**': ['globaltoc.html', - 'relations.html', - 'sourcelink.html', - 'searchbox.html'] -} +html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/modules/elastic.rst b/docs/modules/elastic.rst index c757b67a7..0f14880b7 100644 --- a/docs/modules/elastic.rst +++ b/docs/modules/elastic.rst @@ -20,22 +20,28 @@ The following are a list of options to configure the Elastic Module for MMS. The transport protocol to use to connect to the Elasticsearch server or cluster. Required. elasticsearch.limit.result - The maximum number of results a single search request should return. Optional. Default: 10000 + The maximum number of results a single search request should return. Optional. + `Default: 10000` elasticsearch.limit.term=1000 - The maximum number of terms that a search query should contain. Optional. Default: 1000 + The maximum number of terms that a search query should contain. Optional. + `Default: 1000` elasticsearch.limit.scrollTimeout - The maximum time to wait for search requests. Optional. Default: 1000 + The maximum time to wait for search requests. Optional. + `Default: 1000` elasticsearch.limit.get - The maximum number of elements that a single get request should return. Optional. Default: 5000 + The maximum number of elements that a single get request should return. Optional. + `Default: 5000` elasticsearch.limit.index - The maximum number of elements that will be indexed in a single bulk request. Optional. Default: 5000 + The maximum number of elements that will be indexed in a single bulk request. Optional. + `Default: 5000` elasticsearch.limit.commit - The maximum number of elements to limit commit objects to. Set this to a reasonable size in order to avoid object size limitations in Elasticsearch. + The maximum number of elements to limit commit objects. Set this to a reasonable size in order to avoid object size limitations in Elasticsearch. + `Default: 10000` Elastic Mappings **************** diff --git a/docs/modules/ldap.rst b/docs/modules/ldap.rst index 07c99c311..d9a616c74 100644 --- a/docs/modules/ldap.rst +++ b/docs/modules/ldap.rst @@ -24,10 +24,12 @@ Configuration The dn pattern for the user. Required. ldap.user.attributes.username - The attribute to use for the username. Optional. Default: uid + The attribute to use for the username. Optional. + `Default: uid` ldap.user.attributes.email - The attribute to use for the email address. Optional. Default: mail + The attribute to use for the email address. Optional. + `Default: mail` ldap.group.role.attribute The attribute to use for the group role. Optional. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 594f9591d..2b258046f 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -17,24 +17,24 @@ Dependencies Install postgres (PostgreSQL) 11, instructions for Docker: `PostgreSQL with Docker `_ :: - `docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 --name=postgres postgres:11-alpine` + docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 --name=postgres postgres:11-alpine Or mysql: `Mysql with Docker `_ :: - `docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 --name=mysql mysql:5.7` + docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 --name=mysql mysql:5.7 Elasticsearch Install Elasticsearch 7.8. If you use Docker instructions are available here: `Setting up Elasticsearch with Docker `_ :: - `docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" --name=elasticsearch docker.elastic.co/elasticsearch/elasticsearch:7.8.1` + docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" --name=elasticsearch docker.elastic.co/elasticsearch/elasticsearch:7.8.1 MinIO Install MinIO for artifact storage. `Instructions for MinIO `_ :: - `docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" --name=minio minio/minio server /data` + docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" --name=minio minio/minio server /data Running MMS *********** @@ -46,19 +46,19 @@ Running MMS First, create a container from an MMS image. In the example below, the container is using the host network for simplicity. :: - `docker create --name=mms --network="host" -e "SPRING_CONFIG_LOCATION=/mms.properties" openmbee/mms:4.0.0-b5` + docker create --name=mms --network="host" -e "SPRING_CONFIG_LOCATION=/mms.properties" openmbee/mms:4.0.0-b5 Copy properties If using the above command, copy the properties file to the defined spring config location. :: - `docker cp mms.properties mms:/mms.properties` + docker cp mms.properties mms:/mms.properties Start the container Finally, start the container with the injected properties file. :: - `docker start mms` + docker start mms More Information **************** From a18ec74ec49c0825aae9309f76d75910e53f2705 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:14:20 -0800 Subject: [PATCH 08/26] Add back sphinx_rtd_theme --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index f705791fa..2b469ac88 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx_rtd_theme' ] # Add any paths that contain templates here, relative to this directory. @@ -51,7 +52,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, From cae1c681172451385e22a4645b9257ed9a4f477f Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:25:32 -0800 Subject: [PATCH 09/26] More minor formatting --- docs/modules/elastic.rst | 18 ++++++++++++------ docs/modules/ldap.rst | 6 ++++-- docs/modules/storage.rst | 3 ++- 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/modules/elastic.rst b/docs/modules/elastic.rst index 0f14880b7..a2c4a5274 100644 --- a/docs/modules/elastic.rst +++ b/docs/modules/elastic.rst @@ -21,27 +21,33 @@ The following are a list of options to configure the Elastic Module for MMS. elasticsearch.limit.result The maximum number of results a single search request should return. Optional. - `Default: 10000` + + | `Default: 10000` elasticsearch.limit.term=1000 The maximum number of terms that a search query should contain. Optional. - `Default: 1000` + + | `Default: 1000` elasticsearch.limit.scrollTimeout The maximum time to wait for search requests. Optional. - `Default: 1000` + + | `Default: 1000` elasticsearch.limit.get The maximum number of elements that a single get request should return. Optional. - `Default: 5000` + + | `Default: 5000` elasticsearch.limit.index The maximum number of elements that will be indexed in a single bulk request. Optional. - `Default: 5000` + + | `Default: 5000` elasticsearch.limit.commit The maximum number of elements to limit commit objects. Set this to a reasonable size in order to avoid object size limitations in Elasticsearch. - `Default: 10000` + + | `Default: 10000` Elastic Mappings **************** diff --git a/docs/modules/ldap.rst b/docs/modules/ldap.rst index d9a616c74..5774cb0a5 100644 --- a/docs/modules/ldap.rst +++ b/docs/modules/ldap.rst @@ -25,11 +25,13 @@ Configuration ldap.user.attributes.username The attribute to use for the username. Optional. - `Default: uid` + + | `Default: uid` ldap.user.attributes.email The attribute to use for the email address. Optional. - `Default: mail` + + | `Default: mail` ldap.group.role.attribute The attribute to use for the group role. Optional. diff --git a/docs/modules/storage.rst b/docs/modules/storage.rst index f7c223513..156e9c804 100644 --- a/docs/modules/storage.rst +++ b/docs/modules/storage.rst @@ -19,4 +19,5 @@ Configuration s3.bucket This is the name of the S3 bucket. Optional. - `Default: mms` \ No newline at end of file + + | `Default: mms` \ No newline at end of file From 3740a12d28ae3ffd86acdb524d34e0f0052f4a29 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:31:51 -0800 Subject: [PATCH 10/26] Remove unnecessary backticks --- docs/modules/rdb.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/modules/rdb.rst b/docs/modules/rdb.rst index 01ff5b00d..34e2fcd37 100644 --- a/docs/modules/rdb.rst +++ b/docs/modules/rdb.rst @@ -44,6 +44,6 @@ These properties are required for the MMS application to provide all available f :: - `spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true` - `spring.jpa.open-in-view=false` - `spring.main.allow-bean-definition-overriding=true` \ No newline at end of file + spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true + spring.jpa.open-in-view=false + spring.main.allow-bean-definition-overriding=true \ No newline at end of file From ef47d783eea0fb5f4f66156aad7526c932109771 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:35:47 -0800 Subject: [PATCH 11/26] Redundant --- docs/modules/json.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/json.rst b/docs/modules/json.rst index 77bcc11a3..38f918cd6 100644 --- a/docs/modules/json.rst +++ b/docs/modules/json.rst @@ -3,4 +3,4 @@ JSON ==== -The JSON Module provides data objects for marshalling JSON to and from Java POJOs \ No newline at end of file +The JSON Module provides data objects for marshalling JSON to and from POJOs \ No newline at end of file From 795fc7c1d1fd88e411c19b8b9aa2559cdb173150 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:39:40 -0800 Subject: [PATCH 12/26] Various typos --- docs/modules/artifacts.rst | 2 +- docs/modules/authenticator.rst | 2 +- docs/modules/elastic.rst | 2 +- docs/modules/twc.rst | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/modules/artifacts.rst b/docs/modules/artifacts.rst index b35c7392c..3a3cde6ac 100644 --- a/docs/modules/artifacts.rst +++ b/docs/modules/artifacts.rst @@ -3,4 +3,4 @@ Artifacts ========= -Artifacts is an interface to implement for artifact object support. See :ref:`storage`. for the default implementation. +Artifacts is an interface to implement for artifact object support. See :ref:`storage` for the default implementation. diff --git a/docs/modules/authenticator.rst b/docs/modules/authenticator.rst index 12830f2ba..9137a355d 100644 --- a/docs/modules/authenticator.rst +++ b/docs/modules/authenticator.rst @@ -3,4 +3,4 @@ Authenticator ============= -Authenticator is an interface to implement for authentication. See :ref:`localuser`. or :ref:`ldap`. for implementations. \ No newline at end of file +Authenticator is an interface to implement for authentication. See :ref:`localuser` or :ref:`ldap` for implementations. \ No newline at end of file diff --git a/docs/modules/elastic.rst b/docs/modules/elastic.rst index a2c4a5274..6e5702613 100644 --- a/docs/modules/elastic.rst +++ b/docs/modules/elastic.rst @@ -24,7 +24,7 @@ The following are a list of options to configure the Elastic Module for MMS. | `Default: 10000` - elasticsearch.limit.term=1000 + elasticsearch.limit.term The maximum number of terms that a search query should contain. Optional. | `Default: 1000` diff --git a/docs/modules/twc.rst b/docs/modules/twc.rst index 337948254..03575e8fd 100644 --- a/docs/modules/twc.rst +++ b/docs/modules/twc.rst @@ -7,7 +7,7 @@ The TWC Module provides integration with NoMagic's Teamwork Cloud. Configuration ************* -The TWC Module support multiple instances of TWC. The following configuration are available, where twc.instances is a list. +The TWC Module supports multiple instances of TWC. The following configuration are available, where twc.instances is a list. twc.instances[i].url The url of the ReST interface of TWC. From 68f84941b89beca5229819eb1a522da4b4fc5b5d Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 16:55:13 -0800 Subject: [PATCH 13/26] Changes to styling --- docs/deployment.rst | 7 ++++--- docs/index.rst | 4 +--- docs/installation.rst | 1 + docs/modules/artifacts.rst | 1 + docs/modules/authenticator.rst | 3 ++- docs/modules/cameo.rst | 1 + docs/modules/core.rst | 1 + docs/modules/crud.rst | 1 + docs/modules/data.rst | 1 + docs/modules/elastic.rst | 5 +++-- docs/modules/index.rst | 1 + docs/modules/json.rst | 1 + docs/modules/jupyter.rst | 1 + docs/modules/ldap.rst | 3 ++- docs/modules/localuser.rst | 3 ++- docs/modules/permissions.rst | 1 + docs/modules/rdb.rst | 5 +++-- docs/modules/search.rst | 1 + docs/modules/storage.rst | 3 ++- docs/modules/twc.rst | 4 +++- docs/modules/webhooks.rst | 1 + docs/overview.rst | 3 +-- docs/quickstart.rst | 12 ++++++++---- 23 files changed, 43 insertions(+), 21 deletions(-) diff --git a/docs/deployment.rst b/docs/deployment.rst index 71ebe20d2..6b76d31e6 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -1,16 +1,17 @@ .. _deployment: +========== Deployment -============ +========== Bare Metal -********** +---------- :: java -jar mms-4.0.0.jar Docker -****** +------ :: docker run mms diff --git a/docs/index.rst b/docs/index.rst index bd8574c6f..0c7dbe171 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,9 +7,7 @@ Welcome to Model Management System's documentation! =================================================== -The Model Management System (MMS) provide services for managing models and is a version control system for structured data. It exposes model information through RESTful web services that can be used for CRUD operations, branching, and tagging of the model repository. This heart of the MMS is the View Service which supports the transclusion features of Views. - -The MMS also provides web services for storing and searching Jupyter Lab notebooks. +.. include:: overview.rst .. toctree:: :maxdepth: 2 diff --git a/docs/installation.rst b/docs/installation.rst index b02c88209..7b0b0b5f1 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,5 +1,6 @@ .. _installation: +============ Installation ============ diff --git a/docs/modules/artifacts.rst b/docs/modules/artifacts.rst index 3a3cde6ac..2f20a4e11 100644 --- a/docs/modules/artifacts.rst +++ b/docs/modules/artifacts.rst @@ -1,5 +1,6 @@ .. _artifacts: +========= Artifacts ========= diff --git a/docs/modules/authenticator.rst b/docs/modules/authenticator.rst index 9137a355d..bf2c33218 100644 --- a/docs/modules/authenticator.rst +++ b/docs/modules/authenticator.rst @@ -1,6 +1,7 @@ .. _authenticator: +============= Authenticator ============= -Authenticator is an interface to implement for authentication. See :ref:`localuser` or :ref:`ldap` for implementations. \ No newline at end of file +Authenticator is an interface to implement for authentication. See :ref: `localuser` or :ref:`ldap` for implementations. \ No newline at end of file diff --git a/docs/modules/cameo.rst b/docs/modules/cameo.rst index a4e48cc4b..d8d0ea1f7 100644 --- a/docs/modules/cameo.rst +++ b/docs/modules/cameo.rst @@ -1,5 +1,6 @@ .. _cameo: +===== Cameo ===== diff --git a/docs/modules/core.rst b/docs/modules/core.rst index 6969d3d94..b1d1d0799 100644 --- a/docs/modules/core.rst +++ b/docs/modules/core.rst @@ -1,5 +1,6 @@ .. _core: +==== Core ==== diff --git a/docs/modules/crud.rst b/docs/modules/crud.rst index 774313f65..d5442bdd1 100644 --- a/docs/modules/crud.rst +++ b/docs/modules/crud.rst @@ -1,5 +1,6 @@ .. _crud: +==== CRUD ==== diff --git a/docs/modules/data.rst b/docs/modules/data.rst index 15c4a1de8..e90c2524a 100644 --- a/docs/modules/data.rst +++ b/docs/modules/data.rst @@ -1,5 +1,6 @@ .. _data: +==== Data ==== diff --git a/docs/modules/elastic.rst b/docs/modules/elastic.rst index 6e5702613..1bd58827e 100644 --- a/docs/modules/elastic.rst +++ b/docs/modules/elastic.rst @@ -1,12 +1,13 @@ .. _elastic: +======= Elastic ======= The Elastic Module implements the NodeIndex interface from the crud module. Configuration -************* +------------- The following are a list of options to configure the Elastic Module for MMS. @@ -50,6 +51,6 @@ The following are a list of options to configure the Elastic Module for MMS. | `Default: 10000` Elastic Mappings -**************** +---------------- Elastic mappings are necessary to index fields correctly in Elasticsearch. These mappings are available `here `_. \ No newline at end of file diff --git a/docs/modules/index.rst b/docs/modules/index.rst index ff415c5b1..cdf87d33f 100644 --- a/docs/modules/index.rst +++ b/docs/modules/index.rst @@ -1,5 +1,6 @@ .. _modules: +======= Modules ======= diff --git a/docs/modules/json.rst b/docs/modules/json.rst index 38f918cd6..84e73ace2 100644 --- a/docs/modules/json.rst +++ b/docs/modules/json.rst @@ -1,5 +1,6 @@ .. _json: +==== JSON ==== diff --git a/docs/modules/jupyter.rst b/docs/modules/jupyter.rst index 414acf9c7..5b03a1818 100644 --- a/docs/modules/jupyter.rst +++ b/docs/modules/jupyter.rst @@ -1,5 +1,6 @@ .. _jupyter: +======= Jupyter ======= diff --git a/docs/modules/ldap.rst b/docs/modules/ldap.rst index 5774cb0a5..fe1fddaa1 100644 --- a/docs/modules/ldap.rst +++ b/docs/modules/ldap.rst @@ -1,12 +1,13 @@ .. _ldap: +==== LDAP ==== The LDAP Module provides the ability to authenticate users from an LDAP Identity provider. Configuration -************* +------------- ldap.provider.base The base string to use. Required. diff --git a/docs/modules/localuser.rst b/docs/modules/localuser.rst index 815438519..f53915cba 100644 --- a/docs/modules/localuser.rst +++ b/docs/modules/localuser.rst @@ -1,12 +1,13 @@ .. _localuser: +========= Localuser ========= The LocalUser module provides the ability to authenticate users in the common database. Currently, the main functionality is to set a local admin user during initialization. Configuration -************* +------------- mms.admin.username The root admin username to use. diff --git a/docs/modules/permissions.rst b/docs/modules/permissions.rst index 943f97a2c..29660625f 100644 --- a/docs/modules/permissions.rst +++ b/docs/modules/permissions.rst @@ -1,5 +1,6 @@ .. _permissions: +=========== Permissions =========== diff --git a/docs/modules/rdb.rst b/docs/modules/rdb.rst index 34e2fcd37..36175895b 100644 --- a/docs/modules/rdb.rst +++ b/docs/modules/rdb.rst @@ -1,12 +1,13 @@ .. _rdb: +=== RDB === The RDB Module implements the JPA Repositories defined in the CRUD Module. Configuration -************* +------------- The following are a list of options to configure the RDB Module for MMS. @@ -38,7 +39,7 @@ The following are a list of options to configure the RDB Module for MMS. The DDL generation option. Accepted values are `none`, `create`, `create-drop`, `validate`, and `update` Required. Required Properties -******************* +------------------- These properties are required for the MMS application to provide all available features. They are set by default, but are listed here for completeness. diff --git a/docs/modules/search.rst b/docs/modules/search.rst index 6df37dfa3..e3605a649 100644 --- a/docs/modules/search.rst +++ b/docs/modules/search.rst @@ -1,5 +1,6 @@ .. _mmssearch: +====== Search ====== diff --git a/docs/modules/storage.rst b/docs/modules/storage.rst index 156e9c804..10b853b21 100644 --- a/docs/modules/storage.rst +++ b/docs/modules/storage.rst @@ -1,12 +1,13 @@ .. _storage: +======= Storage ======= Storage is the default implementation of the Artifact interface. It is compatible with S3 compliant APIs. Configuration -************* +------------- s3.access_key This is the access key for the S3 bucket. Required. diff --git a/docs/modules/twc.rst b/docs/modules/twc.rst index 03575e8fd..7a6d1e968 100644 --- a/docs/modules/twc.rst +++ b/docs/modules/twc.rst @@ -1,12 +1,14 @@ .. _twc: +=== TWC === The TWC Module provides integration with NoMagic's Teamwork Cloud. Configuration -************* +------------- + The TWC Module supports multiple instances of TWC. The following configuration are available, where twc.instances is a list. twc.instances[i].url diff --git a/docs/modules/webhooks.rst b/docs/modules/webhooks.rst index 6ae0c02a2..5363e0522 100644 --- a/docs/modules/webhooks.rst +++ b/docs/modules/webhooks.rst @@ -1,5 +1,6 @@ .. _webhooks: +======== Webhooks ======== diff --git a/docs/overview.rst b/docs/overview.rst index 0f6e4612c..3c45d7d29 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,5 +1,4 @@ -.. _overview: - +======== Overview ======== diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 2b258046f..ebe9cb083 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,12 +1,14 @@ .. _quickstart: +=========== Quick Start -============ +=========== This quick start will focus on running all dependencies and the MMS application as docker containers. This is most suitable for testing environments. For production deployments, we recommend the `MMS Reference Implementation `_ as a starting point. Dependencies -************ +------------ + Docker We suggest using Docker to set up PostgreSQL and Elasticsearch. Installation instructions are found here: `Docker documentation `_ @@ -37,7 +39,8 @@ Dependencies docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" --name=minio minio/minio server /data Running MMS -*********** +----------- + Configure the application Each module of MMS can define configuration properties required to function. These properties can be defined in a single location, by default, called application.properties. Place application.properties in the classpath for MMS to use the defined values. For an example, see `example application.properties `_ Alternatively, the properties file can be given by defining the environment variable `SPRING_CONFIG_LOCATION`. @@ -61,5 +64,6 @@ Running MMS docker start mms More Information -**************** +---------------- + For more information and hints, check the `docker-compose.yml `_ in the project root to see how we stand up an instance for testing purposes. \ No newline at end of file From 484c9bb8d47dd8d66c39f5b4b4c6f8fe16637452 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 3 Feb 2021 19:49:00 -0800 Subject: [PATCH 14/26] Remove reference to sdvc --- build.gradle | 2 +- docs/modules/authenticator.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/build.gradle b/build.gradle index 82c35ae8e..779f1045a 100644 --- a/build.gradle +++ b/build.gradle @@ -11,7 +11,7 @@ buildscript { } } -description = 'Structured Data Version Control' +description = 'Model Management System Reference Implementation' ext { commonDependencies = [ diff --git a/docs/modules/authenticator.rst b/docs/modules/authenticator.rst index bf2c33218..dd03f9c0e 100644 --- a/docs/modules/authenticator.rst +++ b/docs/modules/authenticator.rst @@ -4,4 +4,4 @@ Authenticator ============= -Authenticator is an interface to implement for authentication. See :ref: `localuser` or :ref:`ldap` for implementations. \ No newline at end of file +Authenticator is an interface to implement for authentication. See :ref:`localuser` or :ref:`ldap` for implementations. \ No newline at end of file From 3a447ee14e0b49d61a02a9afa7b909561a0baf23 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Mon, 8 Feb 2021 09:33:44 -0800 Subject: [PATCH 15/26] Add some information for permissions. --- docs/modules/permissions.rst | 68 +++++++++++++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/docs/modules/permissions.rst b/docs/modules/permissions.rst index 29660625f..184a98047 100644 --- a/docs/modules/permissions.rst +++ b/docs/modules/permissions.rst @@ -4,4 +4,70 @@ Permissions =========== -The Permissions Module provides permissions to MMS. \ No newline at end of file +The Permissions Module provides permissions to MMS. + +===================== +Default Access Levels +===================== + +The MMS includes 3 hierarchical levels of permissions in the default implementation. Permissions are inherited from the parent level. + + Organization level + Permissions on this level are inherited by the Project and Branch level by default. + + Project level + Permissions on this level are inherited by the Branch level by default. + + Branch level + Permissions on this level are not inherited. + +From these levels, 3 levels of access permissions are provided by default: + + Admin + Can read and write all elements. Can also access admin level operations. + + Write + Can read and write all elements on this level. + + Read + Can read all elements on this level. + +=================== +Setting Permissions +=================== + +The Permissions module provides several ReST endpoints for managing permissions. + + /orgs/{orgId}/permissions + Update permissions for organizations. + + /projects/{projectId}/permissions + Update permissions for projects. + + /projects/{projectId}/refs/{refId}/permissions + Update permissions for branches. + +For each of these endpoints, a payload must be sent with acceptable values + +Permissions acceptable values +:: + + { + "users / groups": { + "action": "ADD / REMOVE", + "permissions": [ + { + "name": "USERNAME", + "role": "ADMIN / WRITER / READER" + } + ] + }, + "inherit": true, + "public": true + } + +================ +More Information +================ + +For more information, see the OpenAPI Documentation. \ No newline at end of file From 7d536225808bac70fb64b58e2161ba87159d6051 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 9 Feb 2021 15:01:04 -0800 Subject: [PATCH 16/26] Fix headers --- docs/modules/permissions.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/modules/permissions.rst b/docs/modules/permissions.rst index 184a98047..a2420710d 100644 --- a/docs/modules/permissions.rst +++ b/docs/modules/permissions.rst @@ -6,9 +6,8 @@ Permissions The Permissions Module provides permissions to MMS. -===================== Default Access Levels -===================== +--------------------- The MMS includes 3 hierarchical levels of permissions in the default implementation. Permissions are inherited from the parent level. @@ -32,9 +31,8 @@ From these levels, 3 levels of access permissions are provided by default: Read Can read all elements on this level. -=================== Setting Permissions -=================== +------------------- The Permissions module provides several ReST endpoints for managing permissions. @@ -66,8 +64,7 @@ Permissions acceptable values "public": true } -================ More Information -================ +---------------- For more information, see the OpenAPI Documentation. \ No newline at end of file From 7d0fc7fc3cd7c622b78b5edb5b64f363ae24d0f6 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Tue, 9 Feb 2021 16:00:22 -0800 Subject: [PATCH 17/26] Fix capitalization --- docs/modules/permissions.rst | 2 +- docs/modules/twc.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/modules/permissions.rst b/docs/modules/permissions.rst index a2420710d..c8214e440 100644 --- a/docs/modules/permissions.rst +++ b/docs/modules/permissions.rst @@ -34,7 +34,7 @@ From these levels, 3 levels of access permissions are provided by default: Setting Permissions ------------------- -The Permissions module provides several ReST endpoints for managing permissions. +The Permissions module provides several REST endpoints for managing permissions. /orgs/{orgId}/permissions Update permissions for organizations. diff --git a/docs/modules/twc.rst b/docs/modules/twc.rst index 7a6d1e968..3618f125f 100644 --- a/docs/modules/twc.rst +++ b/docs/modules/twc.rst @@ -12,16 +12,16 @@ Configuration The TWC Module supports multiple instances of TWC. The following configuration are available, where twc.instances is a list. twc.instances[i].url - The url of the ReST interface of TWC. + The url of the REST interface of TWC. twc.instances[i].protocol - The protocol to use for the ReST interface of TWC. + The protocol to use for the REST interface of TWC. twc.instances[i].port - The port for the ReST interface of TWC. + The port for the REST interface of TWC. twc.instances[i].aliases - A list of aliases for the ReST interface of TWC. + A list of aliases for the REST interface of TWC. twc.instances[i].adminUsername The admin username to use with the defined instance. Required. From 5a61b28a42763ed879b109d964e6300b507ad707 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 13:42:33 -0800 Subject: [PATCH 18/26] Reformat markdown file to rst for sphinx support --- README.md | 76 -------------------- README.rst | 123 +++++++++++++++++++++++++++++++++ artifacts/README.md | 30 -------- artifacts/README.rst | 39 +++++++++++ authenticator/README.md | 12 ---- authenticator/README.rst | 22 ++++++ cameo/README.md | 9 --- cameo/README.rst | 13 ++++ core/README.md | 51 -------------- core/README.rst | 61 ++++++++++++++++ crud/README.md | 13 ---- crud/README.rst | 17 +++++ data/README.md | 2 - data/README.rst | 6 ++ docs/modules/artifacts.rst | 8 +-- docs/modules/authenticator.rst | 8 +-- docs/modules/cameo.rst | 8 +-- docs/modules/core.rst | 8 +-- docs/modules/crud.rst | 8 +-- docs/modules/data.rst | 8 +-- docs/modules/elastic.rst | 57 +-------------- docs/modules/json.rst | 8 +-- docs/modules/jupyter.rst | 8 +-- docs/modules/ldap.rst | 45 +----------- docs/modules/localuser.rst | 17 +---- docs/modules/permissions.rst | 71 +------------------ docs/modules/rdb.rst | 51 +------------- docs/modules/search.rst | 8 +-- docs/modules/storage.rst | 25 +------ docs/modules/twc.rst | 61 +--------------- docs/modules/webhooks.rst | 8 +-- elastic/README.md | 5 -- elastic/README.rst | 57 +++++++++++++++ example/README.md | 26 ------- example/README.rst | 45 ++++++++++++ json/{README.md => README.rst} | 7 +- jupyter/README.rst | 7 ++ ldap/README.md | 3 - ldap/README.rst | 43 ++++++++++++ localuser/README.md | 5 -- localuser/README.rst | 17 +++++ permissions/README.md | 4 -- permissions/README.rst | 69 ++++++++++++++++++ rdb/README.md | 9 --- rdb/README.rst | 55 +++++++++++++++ search/README.rst | 6 ++ storage/README.md | 5 -- storage/README.rst | 25 +++++++ twc/README.rst | 59 ++++++++++++++++ webhooks/README.md | 23 ------ webhooks/README.rst | 31 +++++++++ 51 files changed, 717 insertions(+), 665 deletions(-) delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 artifacts/README.md create mode 100644 artifacts/README.rst delete mode 100644 authenticator/README.md create mode 100644 authenticator/README.rst delete mode 100644 cameo/README.md create mode 100644 cameo/README.rst delete mode 100644 core/README.md create mode 100644 core/README.rst delete mode 100644 crud/README.md create mode 100644 crud/README.rst delete mode 100644 data/README.md create mode 100644 data/README.rst delete mode 100644 elastic/README.md create mode 100644 elastic/README.rst delete mode 100644 example/README.md create mode 100644 example/README.rst rename json/{README.md => README.rst} (77%) create mode 100644 jupyter/README.rst delete mode 100644 ldap/README.md create mode 100644 ldap/README.rst delete mode 100644 localuser/README.md create mode 100644 localuser/README.rst delete mode 100644 permissions/README.md create mode 100644 permissions/README.rst delete mode 100644 rdb/README.md create mode 100644 rdb/README.rst create mode 100644 search/README.rst delete mode 100644 storage/README.md create mode 100644 storage/README.rst create mode 100644 twc/README.rst delete mode 100644 webhooks/README.md create mode 100644 webhooks/README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 3ba39ef2e..000000000 --- a/README.md +++ /dev/null @@ -1,76 +0,0 @@ -# MMS Structured Data Version Control -[![Language grade: Java](https://img.shields.io/lgtm/grade/java/g/Open-MBEE/mms.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/Open-MBEE/mms/context:java) [![CircleCI](https://circleci.com/gh/Open-MBEE/mms.svg?style=svg)](https://circleci.com/gh/Open-MBEE/mms) - -The MMS SDVC is a collection of modules built on top of the Spring Framework and is a part of Open-MBEE. For more information about Open-MBEE, visit the [Open-MBEE Website](https://openmbee.org/) - -#### If you are interested in deploying MMS, please see the [MMSRI](https://github.com/Open-MBEE/mmsri) quickstart. - -## Developer Setup -### Docker -We suggest using Docker to set up PostgreSQL and Elasticsearch. Installation -instructions are found here: [Docker documentation](https://docs.docker.com/) - -### Java SE Development Kit 11 -Installation instructions: [JDK-11 download](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) - -### Postgresql -Install postgres (PostgreSQL) 11, instructions for Docker: [PostgreSQL with Docker](https://hub.docker.com/_/postgres) - - docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 postgres:11-alpine - -### or Mysql -5.7 [Mysql Docker](https://hub.docker.com/_/mysql/) - - docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 mysql:5.7 - -### Elasticsearch -Install Elasticsearch 7.8. If you use Docker instructions are available here: [Setting up Elasticsearch with Docker](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html) - - docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.8.1 - -### Artifacts Storage - - docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" minio/minio server /data - -### IntelliJ IDEA - -1. Import Gradle Project to IntelliJ IDEA -2. Ensure that you select JDK 10 or above and search recursively for projects. -3. The `example` subproject will show you how to include the different modules to run as a Spring Boot application. - -### Gradle -A gradle wrapper is included in the root of this repository and can be called from the command line with `./gradlew [command]`. - -### The Example Sub Project: -1. Copy the example properties file in `example/src/main/resources/` as `application.properties` -1. Change values for all the appropriate properties. The example file holds sane values for most properties. -1. Setup Run and Debug configurations. The command line run command is `./gradlew bootRun` -1. Swagger ui at [http://localhost:8080/v3/swagger-ui.html](http://localhost:8080/v3/swagger-ui.html) - -## Running tests - -See README in /example - -## Built With - -* [Spring](https://spring.io) - - -## Contributing - -To learn how you can get involved in a variety of ways, please see [Contributing to OpenMBEE](https://www.openmbee.org/contribute). - -## Versioning - -We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/Open-MBEE/mms.git). - - -## License - -This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details - -## Structure of Modules - -TBA - - diff --git a/README.rst b/README.rst new file mode 100644 index 000000000..81d175838 --- /dev/null +++ b/README.rst @@ -0,0 +1,123 @@ + +MMS Structured Data Version Control +=================================== + + +.. image:: https://img.shields.io/lgtm/grade/java/g/Open-MBEE/mms.svg?logo=lgtm&logoWidth=18 + :target: https://lgtm.com/projects/g/Open-MBEE/mms/context:java + :alt: Language grade: Java + +.. image:: https://circleci.com/gh/Open-MBEE/mms.svg?style=svg + :target: https://circleci.com/gh/Open-MBEE/mms + :alt: CircleCI + + +The MMS SDVC is a collection of modules built on top of the Spring Framework and is a part of Open-MBEE. For more information about Open-MBEE, visit the `Open-MBEE Website `_ + +If you are interested in deploying MMS, please see the `MMSRI `_ quickstart. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developer Setup +--------------- + +Docker +^^^^^^ + +We suggest using Docker to set up PostgreSQL and Elasticsearch. Installation +instructions are found here: `Docker documentation `_ + +Java SE Development Kit 11 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Installation instructions: `JDK-11 download `_ + +Postgresql +^^^^^^^^^^ + +Install postgres (PostgreSQL) 11, instructions for Docker: `PostgreSQL with Docker `_ + +.. code-block:: + + docker run -d -e POSTGRES_PASSWORD=test1234 -e POSTGRES_USER=mmsuser -e POSTGRES_DB=mms -p 5432:5432 postgres:11-alpine + + +or Mysql +^^^^^^^^ + +5.7 `Mysql Docker `_ + +.. code-block:: + + docker run -d -e MYSQL_ROOT_PASSWORD=test1234 -e MYSQL_DATABASE=mms -p 3306:3306 mysql:5.7 + + +Elasticsearch +^^^^^^^^^^^^^ + +Install Elasticsearch 7.8. If you use Docker instructions are available here: `Setting up Elasticsearch with Docker `_ + +.. code-block:: + + docker run -d -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.8.1 + + +Artifacts Storage +^^^^^^^^^^^^^^^^^ + +.. code-block:: + + docker run -d -p 9000:9000 -e "MINIO_ACCESS_KEY=admintest" -e "MINIO_SECRET_KEY=admintest" minio/minio server /data + + +IntelliJ IDEA +^^^^^^^^^^^^^ + + +#. Import Gradle Project to IntelliJ IDEA +#. Ensure that you select JDK 10 or above and search recursively for projects. +#. The ``example`` subproject will show you how to include the different modules to run as a Spring Boot application. + +Gradle +^^^^^^ + +A gradle wrapper is included in the root of this repository and can be called from the command line with ``./gradlew [command]``. + +The Example Sub Project: +^^^^^^^^^^^^^^^^^^^^^^^^ + + +#. Copy the example properties file in ``example/src/main/resources/`` as ``application.properties`` +#. Change values for all the appropriate properties. The example file holds sane values for most properties. +#. Setup Run and Debug configurations. The command line run command is ``./gradlew bootRun`` +#. Swagger ui at `http://localhost:8080/v3/swagger-ui.html `_ + +Running tests +------------- + +See README in /example + +Built With +---------- + + +* `Spring `_ + +Contributing +------------ + +To learn how you can get involved in a variety of ways, please see `Contributing to OpenMBEE `_. + +Versioning +---------- + +We use `SemVer `_ for versioning. For the versions available, see the `tags on this repository `_. + +License +------- + +This project is licensed under the Apache License 2.0 - see the `LICENSE `_ file for details + +Structure of Modules +-------------------- + +TBA diff --git a/artifacts/README.md b/artifacts/README.md deleted file mode 100644 index 01d64a1de..000000000 --- a/artifacts/README.md +++ /dev/null @@ -1,30 +0,0 @@ -## Artifacts - -Allows artifacts (binary objects) to be attached to elements. Attached artifact info are added to an element object under the `_artifacts` key and versioned as part of element data. - - { - "id": "elementId", - "name": "example element with artifact", - "otherKeys": "other values", - "_artifacts": [ - { - "location": "string depends on storage impl", - "locationType": "internal", - "mimetype": "image/svg+xml", - "extension": "svg" - } - ] - } - -Adds endpoints for getting and uploading binary content - -Adds ArtifactStorage interface - this allows different implementations to be used if desired given the right module - - public interface ArtifactStorage { - - byte[] get(String location, ElementJson element, String mimetype); - //returns location - String store(byte[] data, ElementJson element, String mimetype); - } - -see `storage` for an example reference implementation using s3 \ No newline at end of file diff --git a/artifacts/README.rst b/artifacts/README.rst new file mode 100644 index 000000000..5c2aadff0 --- /dev/null +++ b/artifacts/README.rst @@ -0,0 +1,39 @@ +.. _artifacts: + +Artifacts +--------- + +Allows artifacts (binary objects) to be attached to elements. Attached artifact info are added to an element object under the ``_artifacts`` key and versioned as part of element data. + +.. code-block:: + + { + "id": "elementId", + "name": "example element with artifact", + "otherKeys": "other values", + "_artifacts": [ + { + "location": "string depends on storage impl", + "locationType": "internal", + "mimetype": "image/svg+xml", + "extension": "svg" + } + ] + } + + +Adds endpoints for getting and uploading binary content + +Adds ArtifactStorage interface - this allows different implementations to be used if desired given the right module + +.. code-block:: + + public interface ArtifactStorage { + + byte[] get(String location, ElementJson element, String mimetype); + //returns location + String store(byte[] data, ElementJson element, String mimetype); + } + + +see :ref:`storage` for an example reference implementation using s3 diff --git a/authenticator/README.md b/authenticator/README.md deleted file mode 100644 index 9f4b25ae4..000000000 --- a/authenticator/README.md +++ /dev/null @@ -1,12 +0,0 @@ -## Authenticator - -This module leverages Spring Security's authentication manager to try all registered auth checks provided with other modules - -- Adds login endpoint that returns JWT (JSON Web Token) - - token is generated from username and authorities as returned by authentication manager -- Adds JWT Bearer token auth - -### References -- [Overview of Spring Security](https://spring.io/guides/topicals/spring-security-architecture#_authentication_and_access_control) -- [UserDetails](https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/core/userdetails/UserDetails.html) -- [Authentication](https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/core/Authentication.html) \ No newline at end of file diff --git a/authenticator/README.rst b/authenticator/README.rst new file mode 100644 index 000000000..c6a7421e3 --- /dev/null +++ b/authenticator/README.rst @@ -0,0 +1,22 @@ + +Authenticator +------------- + +This module leverages Spring Security's authentication manager to try all registered auth checks provided with other modules + + +* Adds login endpoint that returns JWT (JSON Web Token) + + * token is generated from username and authorities as returned by authentication manager + +* Adds JWT Bearer token auth + +References +^^^^^^^^^^ + + +* `Overview of Spring Security `_ +* `UserDetails `_ +* `Authentication `_ +* :ref:`localuser` +* :ref:`ldap` \ No newline at end of file diff --git a/cameo/README.md b/cameo/README.md deleted file mode 100644 index 857ca72f5..000000000 --- a/cameo/README.md +++ /dev/null @@ -1,9 +0,0 @@ -## Cameo - -This modules adds behavior for `cameo` projects that mimics behavior from [mms 3.x](https://github.com/Open-MBEE/mms-alfresco) AKA Donbot - -For projects created using schema `cameo`, this will: - -- create holding bin elements for the project -- determine element types such as `view`, `document`, `group`, etc and adds endpoints for getting them (as used by [ve](https://github.com/Open-MBEE/ve) and [mdk](https://github.com/Open-MBEE/mdk)) -- will follow mounted projects when getting elements \ No newline at end of file diff --git a/cameo/README.rst b/cameo/README.rst new file mode 100644 index 000000000..3271c88c9 --- /dev/null +++ b/cameo/README.rst @@ -0,0 +1,13 @@ +.. _cameo: + +Cameo +----- + +This modules adds behavior for ``cameo`` projects that mimics behavior from `mms 3.x `_ AKA Donbot + +For projects created using schema ``cameo``\ , this will: + + +* create holding bin elements for the project +* determine element types such as ``view``\ , ``document``\ , ``group``\ , etc and adds endpoints for getting them (as used by `ve `_ and `mdk `_\ ) +* will follow mounted projects when getting elements diff --git a/core/README.md b/core/README.md deleted file mode 100644 index 272966af8..000000000 --- a/core/README.md +++ /dev/null @@ -1,51 +0,0 @@ -## Core - -This contains core configurations, constants, interfaces, and object classes used by all other modules. - -### Core data organization concept - -Org (like github org) -> Project (like git repo) -> Commits and Branches - -The objects being versioned are json objects (with optional binary attachments, see `artifacts` module) - -### DAO interfaces (`dao`) - -Interfaces for metadata and json storage - -### Events (`services`, `pubsub`) - -A default `EventService` that can publish `EventObject` (extension of Spring ApplicationEvent that includes event type, projectId, branchId and payload) - -Other modules can use the publisher to publish and listen to events (ex. `crud` publishes events on commit, branch created, etc and `webhooks` listens for those events) - -### Service interfaces (`services`) - -Major ones are ProjectService, BranchService, NodeService - -Project and Node services can have different implementations based on the project schema in order to provide different behaviors if needed. - -A default schema implementation is registered by the `crud` module, new schemas and service implementations provided by modules need to be registered by injecting and adding to the `ProjectSchemas` under `config` - -see `crud`, `cameo` for examples - -### Security and Permissions (`security`, `config`, `delegation`, `services`) - -Locally, MMS uses role based permissions on the org, project, and branch level, for user and groups. There can be different permission implementations that are delegated to for looking up whether a user has certain privileges to do certain things (ex. can user read from project A/branch b) - -Current roles are ADMIN, READER, WRITER, each grants a set of Privileges like PROJECT_READ, PROJECT_EDIT, etc - -Roles can be assigned to groups per org/project/branch, a user's groups are inferred from Spring Security's `Authentication`'s `getAuthorities` method (it's hijacked a bit to fit what we need), then the user, groups, target object and privilege requested are given to a permission delegate implementation to determine authorization. The permission delegate implementation can do whatever it wants with the input to return true/false. - -A special group/authority that denotes admin status is `mmsadmin`, an authentication provider can add this to the user's authorities to denote admin status and mms will allow operation on all endpoints. - -See `MethodSecurityService` (used by controllers gating access to endpoints) and `PermissionService` - -see `permission` or `twc` for more examples - -## ContextHolder (`config`) - -Instead of passing projectId, branchId everywhere, `ContextHolder` can be used to get/set the context for the thread. - -## Exceptions (`exceptions`) - -Runtime Exceptions that'll return the corresponding http response code \ No newline at end of file diff --git a/core/README.rst b/core/README.rst new file mode 100644 index 000000000..f31c533d6 --- /dev/null +++ b/core/README.rst @@ -0,0 +1,61 @@ +.. _core: + +Core +==== + +This contains core configurations, constants, interfaces, and object classes used by all other modules. + +Core data organization concept +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Org (like github org) -> Project (like git repo) -> Commits and Branches + +The objects being versioned are json objects (with optional binary attachments, see ``artifacts`` module) + +DAO interfaces (\ ``dao``\ ) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interfaces for metadata and json storage + +Events (\ ``services``\ , ``pubsub``\ ) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A default ``EventService`` that can publish ``EventObject`` (extension of Spring ApplicationEvent that includes event type, projectId, branchId and payload) + +Other modules can use the publisher to publish and listen to events (ex. ``crud`` publishes events on commit, branch created, etc and ``webhooks`` listens for those events) + +Service interfaces (\ ``services``\ ) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Major ones are ProjectService, BranchService, NodeService + +Project and Node services can have different implementations based on the project schema in order to provide different behaviors if needed. + +A default schema implementation is registered by the ``crud`` module, new schemas and service implementations provided by modules need to be registered by injecting and adding to the ``ProjectSchemas`` under ``config`` + +see ``crud``\ , ``cameo`` for examples + +Security and Permissions (\ ``security``\ , ``config``\ , ``delegation``\ , ``services``\ ) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Locally, MMS uses role based permissions on the org, project, and branch level, for user and groups. There can be different permission implementations that are delegated to for looking up whether a user has certain privileges to do certain things (ex. can user read from project A/branch b) + +Current roles are ADMIN, READER, WRITER, each grants a set of Privileges like PROJECT_READ, PROJECT_EDIT, etc + +Roles can be assigned to groups per org/project/branch, a user's groups are inferred from Spring Security's ``Authentication``\ 's ``getAuthorities`` method (it's hijacked a bit to fit what we need), then the user, groups, target object and privilege requested are given to a permission delegate implementation to determine authorization. The permission delegate implementation can do whatever it wants with the input to return true/false. + +A special group/authority that denotes admin status is ``mmsadmin``\ , an authentication provider can add this to the user's authorities to denote admin status and mms will allow operation on all endpoints. + +See ``MethodSecurityService`` (used by controllers gating access to endpoints) and ``PermissionService`` + +see ``permission`` or ``twc`` for more examples + +ContextHolder (\ ``config``\ ) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instead of passing projectId, branchId everywhere, ``ContextHolder`` can be used to get/set the context for the thread. + +Exceptions (\ ``exceptions``\ ) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Runtime Exceptions that'll return the corresponding http response code diff --git a/crud/README.md b/crud/README.md deleted file mode 100644 index 8a31601f3..000000000 --- a/crud/README.md +++ /dev/null @@ -1,13 +0,0 @@ -## CRUD - -This provides the main json document/object versioning functionality and endpoints for cruding orgs, projects, branches, elements and commits. - -### Service Factory - -`ServiceFactory` under `services` is used to get the correct service bean for a particular project type/schema. When creating or getting a project or element, the schema of the project is prefixed to "ProjectService" or "NodeService" to construct the name of the bean. A default implementation is provided. - -`defaultNodeService` - allows partial update of an element by merging it with existing version, allows overwrite of existing version by supplied document, also has overridable hooks for modifying data on create/update/get to allow extending of this class instead of another implementation from scratch - -`defaultProjectService` - auto creates `master` branch on project creation - -see `cameo` module for `cameoNodeService` and `cameoProjectService` for an extension example for a different schema \ No newline at end of file diff --git a/crud/README.rst b/crud/README.rst new file mode 100644 index 000000000..8063a2444 --- /dev/null +++ b/crud/README.rst @@ -0,0 +1,17 @@ +.. _crud: + +CRUD +---- + +This provides the main json document/object versioning functionality and endpoints for cruding orgs, projects, branches, elements and commits. + +Service Factory +^^^^^^^^^^^^^^^ + +``ServiceFactory`` under ``services`` is used to get the correct service bean for a particular project type/schema. When creating or getting a project or element, the schema of the project is prefixed to "ProjectService" or "NodeService" to construct the name of the bean. A default implementation is provided. + +``defaultNodeService`` - allows partial update of an element by merging it with existing version, allows overwrite of existing version by supplied document, also has overridable hooks for modifying data on create/update/get to allow extending of this class instead of another implementation from scratch + +``defaultProjectService`` - auto creates ``master`` branch on project creation + +see ``cameo`` module for ``cameoNodeService`` and ``cameoProjectService`` for an extension example for a different schema diff --git a/data/README.md b/data/README.md deleted file mode 100644 index 5652b715e..000000000 --- a/data/README.md +++ /dev/null @@ -1,2 +0,0 @@ -## Data - diff --git a/data/README.rst b/data/README.rst new file mode 100644 index 000000000..7ff9fbffe --- /dev/null +++ b/data/README.rst @@ -0,0 +1,6 @@ +.. _data: + +Data +---- + +The Data Module provides data objects for core MMS functionality. \ No newline at end of file diff --git a/docs/modules/artifacts.rst b/docs/modules/artifacts.rst index 2f20a4e11..958c7466d 100644 --- a/docs/modules/artifacts.rst +++ b/docs/modules/artifacts.rst @@ -1,7 +1 @@ -.. _artifacts: - -========= -Artifacts -========= - -Artifacts is an interface to implement for artifact object support. See :ref:`storage` for the default implementation. +.. include:: ../../artifacts/README.rst \ No newline at end of file diff --git a/docs/modules/authenticator.rst b/docs/modules/authenticator.rst index dd03f9c0e..b84a0b011 100644 --- a/docs/modules/authenticator.rst +++ b/docs/modules/authenticator.rst @@ -1,7 +1 @@ -.. _authenticator: - -============= -Authenticator -============= - -Authenticator is an interface to implement for authentication. See :ref:`localuser` or :ref:`ldap` for implementations. \ No newline at end of file +.. include:: ../../authenticator/README.rst \ No newline at end of file diff --git a/docs/modules/cameo.rst b/docs/modules/cameo.rst index d8d0ea1f7..2a170d303 100644 --- a/docs/modules/cameo.rst +++ b/docs/modules/cameo.rst @@ -1,7 +1 @@ -.. _cameo: - -===== -Cameo -===== - -The Cameo Module adds compatibility for the Cameo Development Kit. \ No newline at end of file +.. include:: ../../cameo/README.rst \ No newline at end of file diff --git a/docs/modules/core.rst b/docs/modules/core.rst index b1d1d0799..96de145d9 100644 --- a/docs/modules/core.rst +++ b/docs/modules/core.rst @@ -1,7 +1 @@ -.. _core: - -==== -Core -==== - -The Core module provides essential classes and helpers for the MMS. \ No newline at end of file +.. include:: ../../core/README.rst \ No newline at end of file diff --git a/docs/modules/crud.rst b/docs/modules/crud.rst index d5442bdd1..32e7b5cfb 100644 --- a/docs/modules/crud.rst +++ b/docs/modules/crud.rst @@ -1,7 +1 @@ -.. _crud: - -==== -CRUD -==== - -The CRUD Module provides default Create, Read, Update, Delete functionality to the MMS. \ No newline at end of file +.. include:: ../../crud/README.rst \ No newline at end of file diff --git a/docs/modules/data.rst b/docs/modules/data.rst index e90c2524a..14d601153 100644 --- a/docs/modules/data.rst +++ b/docs/modules/data.rst @@ -1,7 +1 @@ -.. _data: - -==== -Data -==== - -The Data Module provides data objects for core MMS functionality. \ No newline at end of file +.. include:: ../../data/README.rst \ No newline at end of file diff --git a/docs/modules/elastic.rst b/docs/modules/elastic.rst index 1bd58827e..7b36dc99e 100644 --- a/docs/modules/elastic.rst +++ b/docs/modules/elastic.rst @@ -1,56 +1 @@ -.. _elastic: - -======= -Elastic -======= - -The Elastic Module implements the NodeIndex interface from the crud module. - -Configuration -------------- - -The following are a list of options to configure the Elastic Module for MMS. - - elasticsearch.host - The host name of the Elasticsearch server or cluster. Required. - - elasticsearch.port - The port number of the Elasticsearch server or cluster. Required. - - elasticsearch.http - The transport protocol to use to connect to the Elasticsearch server or cluster. Required. - - elasticsearch.limit.result - The maximum number of results a single search request should return. Optional. - - | `Default: 10000` - - elasticsearch.limit.term - The maximum number of terms that a search query should contain. Optional. - - | `Default: 1000` - - elasticsearch.limit.scrollTimeout - The maximum time to wait for search requests. Optional. - - | `Default: 1000` - - elasticsearch.limit.get - The maximum number of elements that a single get request should return. Optional. - - | `Default: 5000` - - elasticsearch.limit.index - The maximum number of elements that will be indexed in a single bulk request. Optional. - - | `Default: 5000` - - elasticsearch.limit.commit - The maximum number of elements to limit commit objects. Set this to a reasonable size in order to avoid object size limitations in Elasticsearch. - - | `Default: 10000` - -Elastic Mappings ----------------- - -Elastic mappings are necessary to index fields correctly in Elasticsearch. These mappings are available `here `_. \ No newline at end of file +.. include:: ../../elastic/README.rst \ No newline at end of file diff --git a/docs/modules/json.rst b/docs/modules/json.rst index 84e73ace2..feba4060c 100644 --- a/docs/modules/json.rst +++ b/docs/modules/json.rst @@ -1,7 +1 @@ -.. _json: - -==== -JSON -==== - -The JSON Module provides data objects for marshalling JSON to and from POJOs \ No newline at end of file +.. include:: ../../json/README.rst \ No newline at end of file diff --git a/docs/modules/jupyter.rst b/docs/modules/jupyter.rst index 5b03a1818..c44e6ebf5 100644 --- a/docs/modules/jupyter.rst +++ b/docs/modules/jupyter.rst @@ -1,7 +1 @@ -.. _jupyter: - -======= -Jupyter -======= - -The Jupyter module adds the ability to support jupyter notebooks. \ No newline at end of file +.. include:: ../../jupyter/README.rst \ No newline at end of file diff --git a/docs/modules/ldap.rst b/docs/modules/ldap.rst index fe1fddaa1..27acf0b31 100644 --- a/docs/modules/ldap.rst +++ b/docs/modules/ldap.rst @@ -1,44 +1 @@ -.. _ldap: - -==== -LDAP -==== - -The LDAP Module provides the ability to authenticate users from an LDAP Identity provider. - -Configuration -------------- - - ldap.provider.base - The base string to use. Required. - - ldap.provider.url - The provider url, including the base. Required. - - ldap.provider.userdn - The userdn to use to authenticate to the provider. Optional. - - ldap.provider.password - The password to use to authenticate to the provider. Optional. - - ldap.user.dn.pattern - The dn pattern for the user. Required. - - ldap.user.attributes.username - The attribute to use for the username. Optional. - - | `Default: uid` - - ldap.user.attributes.email - The attribute to use for the email address. Optional. - - | `Default: mail` - - ldap.group.role.attribute - The attribute to use for the group role. Optional. - - ldap.group.search.base - The base for group search. Optional. - - ldap.group.search.filter - The search filter for group search. Optional. +.. include:: ../../ldap/README.rst \ No newline at end of file diff --git a/docs/modules/localuser.rst b/docs/modules/localuser.rst index f53915cba..352f2ce41 100644 --- a/docs/modules/localuser.rst +++ b/docs/modules/localuser.rst @@ -1,16 +1 @@ -.. _localuser: - -========= -Localuser -========= - -The LocalUser module provides the ability to authenticate users in the common database. Currently, the main functionality is to set a local admin user during initialization. - -Configuration -------------- - - mms.admin.username - The root admin username to use. - - mms.admin.password - The root admin password to use. \ No newline at end of file +.. include:: ../../localuser/README.rst \ No newline at end of file diff --git a/docs/modules/permissions.rst b/docs/modules/permissions.rst index c8214e440..6130ddce8 100644 --- a/docs/modules/permissions.rst +++ b/docs/modules/permissions.rst @@ -1,70 +1 @@ -.. _permissions: - -=========== -Permissions -=========== - -The Permissions Module provides permissions to MMS. - -Default Access Levels ---------------------- - -The MMS includes 3 hierarchical levels of permissions in the default implementation. Permissions are inherited from the parent level. - - Organization level - Permissions on this level are inherited by the Project and Branch level by default. - - Project level - Permissions on this level are inherited by the Branch level by default. - - Branch level - Permissions on this level are not inherited. - -From these levels, 3 levels of access permissions are provided by default: - - Admin - Can read and write all elements. Can also access admin level operations. - - Write - Can read and write all elements on this level. - - Read - Can read all elements on this level. - -Setting Permissions -------------------- - -The Permissions module provides several REST endpoints for managing permissions. - - /orgs/{orgId}/permissions - Update permissions for organizations. - - /projects/{projectId}/permissions - Update permissions for projects. - - /projects/{projectId}/refs/{refId}/permissions - Update permissions for branches. - -For each of these endpoints, a payload must be sent with acceptable values - -Permissions acceptable values -:: - - { - "users / groups": { - "action": "ADD / REMOVE", - "permissions": [ - { - "name": "USERNAME", - "role": "ADMIN / WRITER / READER" - } - ] - }, - "inherit": true, - "public": true - } - -More Information ----------------- - -For more information, see the OpenAPI Documentation. \ No newline at end of file +.. include:: ../../permissions/README.rst \ No newline at end of file diff --git a/docs/modules/rdb.rst b/docs/modules/rdb.rst index 36175895b..26625705a 100644 --- a/docs/modules/rdb.rst +++ b/docs/modules/rdb.rst @@ -1,50 +1 @@ -.. _rdb: - -=== -RDB -=== - -The RDB Module implements the JPA Repositories defined in the CRUD Module. - -Configuration -------------- - -The following are a list of options to configure the RDB Module for MMS. - - spring.datasource.url - The datasource url in jdbc format. Required. - - spring.datasource.database - The database name to use for global MMS configuration. Required. - - spring.datasource.username - The username to use for authentication. Optional. - - spring.datasource.password - The password to use for authentication. Optional. - - spring.datasource.driver-class-name - The driver to use for JDBC. Any database driver supported by Spring Data can be used. Required. - - spring.datasource.initialization-mode - The initialization mode to use when starting the MMS application. Accepted values are `always`, `embedded`, and `never`. Required. - - spring.jpa.properties.hibernate.dialect - The hibernate dialect to use. Required. - - spring.jpa.properties.hibernate.dialect.storage_engine - The storage engine to use. Optional. - - spring.jpa.hibernate.ddl-auto - The DDL generation option. Accepted values are `none`, `create`, `create-drop`, `validate`, and `update` Required. - -Required Properties -------------------- - -These properties are required for the MMS application to provide all available features. They are set by default, but are listed here for completeness. - - :: - - spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true - spring.jpa.open-in-view=false - spring.main.allow-bean-definition-overriding=true \ No newline at end of file +.. include:: ../../rdb/README.rst \ No newline at end of file diff --git a/docs/modules/search.rst b/docs/modules/search.rst index e3605a649..26625705a 100644 --- a/docs/modules/search.rst +++ b/docs/modules/search.rst @@ -1,7 +1 @@ -.. _mmssearch: - -====== -Search -====== - -The Search Module \ No newline at end of file +.. include:: ../../rdb/README.rst \ No newline at end of file diff --git a/docs/modules/storage.rst b/docs/modules/storage.rst index 10b853b21..786b82846 100644 --- a/docs/modules/storage.rst +++ b/docs/modules/storage.rst @@ -1,24 +1 @@ -.. _storage: - -======= -Storage -======= - -Storage is the default implementation of the Artifact interface. It is compatible with S3 compliant APIs. - -Configuration -------------- - - s3.access_key - This is the access key for the S3 bucket. Required. - - s3.secret_key - This is the secret key for the S3 bucket. Required. - - s3.region - This is the region that the S3 bucket is located in. Required. - - s3.bucket - This is the name of the S3 bucket. Optional. - - | `Default: mms` \ No newline at end of file +.. include:: ../../storage/README.rst \ No newline at end of file diff --git a/docs/modules/twc.rst b/docs/modules/twc.rst index 3618f125f..7de72e03e 100644 --- a/docs/modules/twc.rst +++ b/docs/modules/twc.rst @@ -1,60 +1 @@ -.. _twc: - -=== -TWC -=== - -The TWC Module provides integration with NoMagic's Teamwork Cloud. - -Configuration -------------- - -The TWC Module supports multiple instances of TWC. The following configuration are available, where twc.instances is a list. - - twc.instances[i].url - The url of the REST interface of TWC. - - twc.instances[i].protocol - The protocol to use for the REST interface of TWC. - - twc.instances[i].port - The port for the REST interface of TWC. - - twc.instances[i].aliases - A list of aliases for the REST interface of TWC. - - twc.instances[i].adminUsername - The admin username to use with the defined instance. Required. - - twc.instances[i].adminPwd - The admin password to use with the defined instance. Required. - - twc.instances[i].roles.project_read - The TWC roles to use for MMS project_read permissions. - - twc.instances[i].roles.project_read_commits - The TWC roles to use for MMS project_read_commits permissions. - - twc.instances[i].roles.project_read_permissions - The TWC roles to use for MMS project_read_permissions permissions. - - twc.instances[i].roles.project_edit - The TWC roles to use for MMS project_edit permissions. - - twc.instances[i].roles.project_create_branch - The TWC roles to use for MMS project_create_branch permissions. - - twc.instances[i].roles.project_update_permissions - The TWC roles to use for MMS project_update_permissions permissions. - - twc.instances[i].roles.branch_read - The TWC roles to use for MMS branch_read permissions. - - twc.instances[i].roles.branch_read_permissions - The TWC roles to use for MMS branch_read_permissions permissions. - - twc.instances[i].roles.branch_edit_content - The TWC roles to use for MMS branch_edit_content permissions. - - twc.instances[i].roles.branch_update_permissions - The TWC roles to use for MMS branch_update_permissions permissions. \ No newline at end of file +.. include:: ../../twc/README.rst \ No newline at end of file diff --git a/docs/modules/webhooks.rst b/docs/modules/webhooks.rst index 5363e0522..a85ed7039 100644 --- a/docs/modules/webhooks.rst +++ b/docs/modules/webhooks.rst @@ -1,7 +1 @@ -.. _webhooks: - -======== -Webhooks -======== - -The Webhooks Module provides webhook support for event driven notifications. \ No newline at end of file +.. include:: ../../webhooks/README.rst \ No newline at end of file diff --git a/elastic/README.md b/elastic/README.md deleted file mode 100644 index 515d3daa5..000000000 --- a/elastic/README.md +++ /dev/null @@ -1,5 +0,0 @@ -## Elastic - -Elasticsearch implementation for json document storage, indexing and search. Implements the `*IndexDAO` and `SearchService` interfaces from `core` - -On project creation, will look for a mapping file based on the project schema prefixed to '_node.json' under $classpath/elastic_mappings, otherwise will use elastic_mappins/default_node.json for field mapping \ No newline at end of file diff --git a/elastic/README.rst b/elastic/README.rst new file mode 100644 index 000000000..fb849369d --- /dev/null +++ b/elastic/README.rst @@ -0,0 +1,57 @@ +.. _elastic: + +Elastic +------- + +Elasticsearch implementation for json document storage, indexing and search. Implements the ``*IndexDAO`` and ``SearchService`` interfaces from ``core`` + +On project creation, will look for a mapping file based on the project schema prefixed to '_node.json' under $classpath/elastic_mappings, otherwise will use elastic_mappins/default_node.json for field mapping + +Configuration +^^^^^^^^^^^^^ + +The following are a list of options to configure the Elastic Module for MMS. + + elasticsearch.host + The host name of the Elasticsearch server or cluster. Required. + + elasticsearch.port + The port number of the Elasticsearch server or cluster. Required. + + elasticsearch.http + The transport protocol to use to connect to the Elasticsearch server or cluster. Required. + + elasticsearch.limit.result + The maximum number of results a single search request should return. Optional. + + | `Default: 10000` + + elasticsearch.limit.term + The maximum number of terms that a search query should contain. Optional. + + | `Default: 1000` + + elasticsearch.limit.scrollTimeout + The maximum time to wait for search requests. Optional. + + | `Default: 1000` + + elasticsearch.limit.get + The maximum number of elements that a single get request should return. Optional. + + | `Default: 5000` + + elasticsearch.limit.index + The maximum number of elements that will be indexed in a single bulk request. Optional. + + | `Default: 5000` + + elasticsearch.limit.commit + The maximum number of elements to limit commit objects. Set this to a reasonable size in order to avoid object size limitations in Elasticsearch. + + | `Default: 10000` + +Elastic Mappings +^^^^^^^^^^^^^^^^ + +Elastic mappings are necessary to index fields correctly in Elasticsearch. These mappings are available `here `_. \ No newline at end of file diff --git a/example/README.md b/example/README.md deleted file mode 100644 index 8a9466acc..000000000 --- a/example/README.md +++ /dev/null @@ -1,26 +0,0 @@ -## Quick Start -### Docker -Installation instructions are found here: [Docker documentation](https://docs.docker.com/) - -1. At repo's root level, run `docker-compose up --build` to create and start all the services from the configuration. This uses the `test` Spring profile -1. Swagger ui at [http://localhost:8080/v3/swagger-ui.html](http://localhost:8080/v3/swagger-ui.html) -1. Use the command `docker-compose down` to stop any containers from running and to remove the containers, networks, and images created by the `docker-compose up` command. This command should always be done before any new attempts to restart the services from the configuration. - - -## Run command line api test - -1. run example app on localhost - 1. if using docker-compose to bring up example app, can do the following to run the tests instead of installing node - - docker run -v $PWD:/etc/newman -t --network container:mms postman/newman:alpine run crud.postman_collection.json --environment="test-env.json" --delay-request=300 - - 1. otherwise [install Node.js](https://nodejs.org/en/download/), if not already installed - 1. copy localhost-env.json.example to localhost-env.json, change values accordingly - - npm install -g newman - - newman run crud.postman_collection.json -e localhost-env.json --delay-request 300 - -## Swagger UI of running app - -Swagger 3 UI at http://localhost:8080/v3/swagger-ui.html \ No newline at end of file diff --git a/example/README.rst b/example/README.rst new file mode 100644 index 000000000..0fab858a6 --- /dev/null +++ b/example/README.rst @@ -0,0 +1,45 @@ + +Quick Start +----------- + +Docker +^^^^^^ + +Installation instructions are found here: `Docker documentation `_ + + +#. At repo's root level, run ``docker-compose up --build`` to create and start all the services from the configuration. This uses the ``test`` Spring profile +#. Swagger ui at `http://localhost:8080/v3/swagger-ui.html `_ +#. Use the command ``docker-compose down`` to stop any containers from running and to remove the containers, networks, and images created by the ``docker-compose up`` command. This command should always be done before any new attempts to restart the services from the configuration. + +Run command line api test +------------------------- + + +#. + run example app on localhost + + + #. + if using docker-compose to bring up example app, can do the following to run the tests instead of installing node + + .. code-block:: + + docker run -v $PWD:/etc/newman -t --network container:mms postman/newman:alpine run crud.postman_collection.json --environment="test-env.json" --delay-request=300 + + #. + otherwise `install Node.js `_\ , if not already installed + + #. + copy localhost-env.json.example to localhost-env.json, change values accordingly + + .. code-block:: + + npm install -g newman + + newman run crud.postman_collection.json -e localhost-env.json --delay-request 300 + +Swagger UI of running app +------------------------- + +Swagger 3 UI at http://localhost:8080/v3/swagger-ui.html diff --git a/json/README.md b/json/README.rst similarity index 77% rename from json/README.md rename to json/README.rst index 22c1e44d7..c7381ee07 100644 --- a/json/README.md +++ b/json/README.rst @@ -1,5 +1,8 @@ -## "JSON" objects +.. _json: + +"JSON" objects +-------------- This module contains classes that provides convenience getter/setters for properties that are defined for each type of object used in mms. All are extended from Map and allow arbitrary extra key/value pairs. -Setters are chained. \ No newline at end of file +Setters are chained. diff --git a/jupyter/README.rst b/jupyter/README.rst new file mode 100644 index 000000000..5b03a1818 --- /dev/null +++ b/jupyter/README.rst @@ -0,0 +1,7 @@ +.. _jupyter: + +======= +Jupyter +======= + +The Jupyter module adds the ability to support jupyter notebooks. \ No newline at end of file diff --git a/ldap/README.md b/ldap/README.md deleted file mode 100644 index 172fad6ea..000000000 --- a/ldap/README.md +++ /dev/null @@ -1,3 +0,0 @@ -## LDAP - -Adds ldap authentication provider, ldap groups the user belongs to that are also assigned a role in mms will be added as the user's granted authorities. \ No newline at end of file diff --git a/ldap/README.rst b/ldap/README.rst new file mode 100644 index 000000000..0fe6a91a6 --- /dev/null +++ b/ldap/README.rst @@ -0,0 +1,43 @@ +.. _ldap: + +LDAP +---- + +Adds ldap authentication provider, ldap groups the user belongs to that are also assigned a role in mms will be added as the user's granted authorities. + +Configuration +^^^^^^^^^^^^^ + + ldap.provider.base + The base string to use. Required. + + ldap.provider.url + The provider url, including the base. Required. + + ldap.provider.userdn + The userdn to use to authenticate to the provider. Optional. + + ldap.provider.password + The password to use to authenticate to the provider. Optional. + + ldap.user.dn.pattern + The dn pattern for the user. Required. + + ldap.user.attributes.username + The attribute to use for the username. Optional. + + | `Default: uid` + + ldap.user.attributes.email + The attribute to use for the email address. Optional. + + | `Default: mail` + + ldap.group.role.attribute + The attribute to use for the group role. Optional. + + ldap.group.search.base + The base for group search. Optional. + + ldap.group.search.filter + The search filter for group search. Optional. diff --git a/localuser/README.md b/localuser/README.md deleted file mode 100644 index 3f56e064c..000000000 --- a/localuser/README.md +++ /dev/null @@ -1,5 +0,0 @@ -## LocalUser authentication - -Adds endpoint for adding local users, admins and changing password, and local authentication provider - -Uses `rdb` for storing user info \ No newline at end of file diff --git a/localuser/README.rst b/localuser/README.rst new file mode 100644 index 000000000..5eb18e86f --- /dev/null +++ b/localuser/README.rst @@ -0,0 +1,17 @@ +.. _localuser: + +LocalUser authentication +------------------------ + +Adds endpoint for adding local users, admins and changing password, and local authentication provider + +Uses * :ref:`rdb` for storing user info + +Configuration +^^^^^^^^^^^^^ + + mms.admin.username + The root admin username to use. + + mms.admin.password + The root admin password to use. diff --git a/permissions/README.md b/permissions/README.md deleted file mode 100644 index d9114df1c..000000000 --- a/permissions/README.md +++ /dev/null @@ -1,4 +0,0 @@ -## Local Permissions - -This module implements local permissions and adds endpoints for modifying and getting permissions - diff --git a/permissions/README.rst b/permissions/README.rst new file mode 100644 index 000000000..7255d92f3 --- /dev/null +++ b/permissions/README.rst @@ -0,0 +1,69 @@ +.. _permissions: + +Local Permissions +----------------- + +This module implements local permissions and adds endpoints for modifying and getting permissions + +Default Access Levels +^^^^^^^^^^^^^^^^^^^^^ + +The MMS includes 3 hierarchical levels of permissions in the default implementation. Permissions are inherited from the parent level. + + Organization level + Permissions on this level are inherited by the Project and Branch level by default. + + Project level + Permissions on this level are inherited by the Branch level by default. + + Branch level + Permissions on this level are not inherited. + +From these levels, 3 levels of access permissions are provided by default: + + Admin + Can read and write all elements. Can also access admin level operations. + + Write + Can read and write all elements on this level. + + Read + Can read all elements on this level. + +Setting Permissions +^^^^^^^^^^^^^^^^^^^ + +The Permissions module provides several REST endpoints for managing permissions. + + /orgs/{orgId}/permissions + Update permissions for organizations. + + /projects/{projectId}/permissions + Update permissions for projects. + + /projects/{projectId}/refs/{refId}/permissions + Update permissions for branches. + +For each of these endpoints, a payload must be sent with acceptable values + +Permissions acceptable values +:: + + { + "users / groups": { + "action": "ADD / REMOVE", + "permissions": [ + { + "name": "USERNAME", + "role": "ADMIN / WRITER / READER" + } + ] + }, + "inherit": true, + "public": true + } + +More Information +^^^^^^^^^^^^^^^^ + +For more information, see the OpenAPI Documentation. \ No newline at end of file diff --git a/rdb/README.md b/rdb/README.md deleted file mode 100644 index 6ad12f454..000000000 --- a/rdb/README.md +++ /dev/null @@ -1,9 +0,0 @@ -## RDB - -Implementation of metadata storage and permissions (if using local user auth/local permissions) - -Uses Spring Data JPA and Hibernate for ORM for main db - -Tested most with PostgreSQL, should also work for MySQL and others - -Currently, a separate database is created for each project, and table for each head of branch. Each table contains pointers to the latest element (json document) for that branch. \ No newline at end of file diff --git a/rdb/README.rst b/rdb/README.rst new file mode 100644 index 000000000..a21628ce2 --- /dev/null +++ b/rdb/README.rst @@ -0,0 +1,55 @@ +.. _rdb: + +RDB +--- + +Implementation of metadata storage and permissions (if using local user auth/local permissions) + +Uses Spring Data JPA and Hibernate for ORM for main db + +Tested most with PostgreSQL, should also work for MySQL and others + +Currently, a separate database is created for each project, and table for each head of branch. Each table contains pointers to the latest element (json document) for that branch. + +Configuration +^^^^^^^^^^^^^ + +The following are a list of options to configure the RDB Module for MMS. + + spring.datasource.url + The datasource url in jdbc format. Required. + + spring.datasource.database + The database name to use for global MMS configuration. Required. + + spring.datasource.username + The username to use for authentication. Optional. + + spring.datasource.password + The password to use for authentication. Optional. + + spring.datasource.driver-class-name + The driver to use for JDBC. Any database driver supported by Spring Data can be used. Required. + + spring.datasource.initialization-mode + The initialization mode to use when starting the MMS application. Accepted values are `always`, `embedded`, and `never`. Required. + + spring.jpa.properties.hibernate.dialect + The hibernate dialect to use. Required. + + spring.jpa.properties.hibernate.dialect.storage_engine + The storage engine to use. Optional. + + spring.jpa.hibernate.ddl-auto + The DDL generation option. Accepted values are `none`, `create`, `create-drop`, `validate`, and `update` Required. + +Required Properties +^^^^^^^^^^^^^^^^^^^ + +These properties are required for the MMS application to provide all available features. They are set by default, but are listed here for completeness. + + :: + + spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true + spring.jpa.open-in-view=false + spring.main.allow-bean-definition-overriding=true \ No newline at end of file diff --git a/search/README.rst b/search/README.rst new file mode 100644 index 000000000..a4e712745 --- /dev/null +++ b/search/README.rst @@ -0,0 +1,6 @@ +.. _mmssearch: + +Search +______ + +The Search Module \ No newline at end of file diff --git a/storage/README.md b/storage/README.md deleted file mode 100644 index e5cba6414..000000000 --- a/storage/README.md +++ /dev/null @@ -1,5 +0,0 @@ -## Storage - -This is an implementation of the `artifacts` interface using s3 and should work with any S3 compatible storage service. - -[MinIO](https://min.io/product/overview) is an open source s3 compatible object storage, it can be used standalone or can add a s3 api layer on top of existing providers using MinIO Gateway, for example, [NAS](https://docs.min.io/docs/minio-gateway-for-nas.html) \ No newline at end of file diff --git a/storage/README.rst b/storage/README.rst new file mode 100644 index 000000000..a26396672 --- /dev/null +++ b/storage/README.rst @@ -0,0 +1,25 @@ +.. _storage: + +Storage +------- + +This is an implementation of the ``artifacts`` interface using s3 and should work with any S3 compatible storage service. + +`MinIO `_ is an open source s3 compatible object storage, it can be used standalone or can add a s3 api layer on top of existing providers using MinIO Gateway, for example, `NAS `_ + +Configuration +^^^^^^^^^^^^^ + + s3.access_key + This is the access key for the S3 bucket. Required. + + s3.secret_key + This is the secret key for the S3 bucket. Required. + + s3.region + This is the region that the S3 bucket is located in. Required. + + s3.bucket + This is the name of the S3 bucket. Optional. + + | `Default: mms` \ No newline at end of file diff --git a/twc/README.rst b/twc/README.rst new file mode 100644 index 000000000..1d0f817b8 --- /dev/null +++ b/twc/README.rst @@ -0,0 +1,59 @@ +.. _twc: + +TWC +--- + +The TWC Module provides integration with NoMagic's Teamwork Cloud. + +Configuration +^^^^^^^^^^^^^ + +The TWC Module supports multiple instances of TWC. The following configuration are available, where twc.instances is a list. + + twc.instances[i].url + The url of the REST interface of TWC. + + twc.instances[i].protocol + The protocol to use for the REST interface of TWC. + + twc.instances[i].port + The port for the REST interface of TWC. + + twc.instances[i].aliases + A list of aliases for the REST interface of TWC. + + twc.instances[i].adminUsername + The admin username to use with the defined instance. Required. + + twc.instances[i].adminPwd + The admin password to use with the defined instance. Required. + + twc.instances[i].roles.project_read + The TWC roles to use for MMS project_read permissions. + + twc.instances[i].roles.project_read_commits + The TWC roles to use for MMS project_read_commits permissions. + + twc.instances[i].roles.project_read_permissions + The TWC roles to use for MMS project_read_permissions permissions. + + twc.instances[i].roles.project_edit + The TWC roles to use for MMS project_edit permissions. + + twc.instances[i].roles.project_create_branch + The TWC roles to use for MMS project_create_branch permissions. + + twc.instances[i].roles.project_update_permissions + The TWC roles to use for MMS project_update_permissions permissions. + + twc.instances[i].roles.branch_read + The TWC roles to use for MMS branch_read permissions. + + twc.instances[i].roles.branch_read_permissions + The TWC roles to use for MMS branch_read_permissions permissions. + + twc.instances[i].roles.branch_edit_content + The TWC roles to use for MMS branch_edit_content permissions. + + twc.instances[i].roles.branch_update_permissions + The TWC roles to use for MMS branch_update_permissions permissions. \ No newline at end of file diff --git a/webhooks/README.md b/webhooks/README.md deleted file mode 100644 index 6ffd92f22..000000000 --- a/webhooks/README.md +++ /dev/null @@ -1,23 +0,0 @@ -## Webhooks - -Adds endpoints for registering webhooks per project - -Current triggers are on commit or branch creation - -Commit event: - - { - "projectId": "projectId", - "branchId": "branchId", - "event": "commit", - "payload": {{see CommitJson}} - } - -Branch event: - - { - "projectId": "projectId", - "branchId": "branchId", - "event": "branch_created", - "payload": {{see RefJson}} - } \ No newline at end of file diff --git a/webhooks/README.rst b/webhooks/README.rst new file mode 100644 index 000000000..b62fb4083 --- /dev/null +++ b/webhooks/README.rst @@ -0,0 +1,31 @@ +.. _webhooks: + +Webhooks +-------- + +Adds endpoints for registering webhooks per project + +Current triggers are on commit or branch creation + +Commit event: + +.. code-block:: + + { + "projectId": "projectId", + "branchId": "branchId", + "event": "commit", + "payload": {{see CommitJson}} + } + + +Branch event: + +.. code-block:: + + { + "projectId": "projectId", + "branchId": "branchId", + "event": "branch_created", + "payload": {{see RefJson}} + } From 827be3549aa9f8044aafcd0f747d2f6c5818be11 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 13:47:56 -0800 Subject: [PATCH 19/26] Fix strange readme header --- json/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/json/README.rst b/json/README.rst index c7381ee07..be8d4efc1 100644 --- a/json/README.rst +++ b/json/README.rst @@ -1,7 +1,7 @@ .. _json: -"JSON" objects --------------- +JSON +---- This module contains classes that provides convenience getter/setters for properties that are defined for each type of object used in mms. All are extended from Map and allow arbitrary extra key/value pairs. From 1eef355612e38db7ba761086c81b620efcd5f889 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 13:52:26 -0800 Subject: [PATCH 20/26] Minor fixes --- docs/modules/search.rst | 2 +- localuser/README.rst | 2 +- permissions/README.rst | 2 +- webhooks/README.rst | 8 ++++---- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/modules/search.rst b/docs/modules/search.rst index 26625705a..3e1155fbd 100644 --- a/docs/modules/search.rst +++ b/docs/modules/search.rst @@ -1 +1 @@ -.. include:: ../../rdb/README.rst \ No newline at end of file +.. include:: ../../search/README.rst \ No newline at end of file diff --git a/localuser/README.rst b/localuser/README.rst index 5eb18e86f..80648fe39 100644 --- a/localuser/README.rst +++ b/localuser/README.rst @@ -5,7 +5,7 @@ LocalUser authentication Adds endpoint for adding local users, admins and changing password, and local authentication provider -Uses * :ref:`rdb` for storing user info +Uses :ref:`rdb` for storing user info Configuration ^^^^^^^^^^^^^ diff --git a/permissions/README.rst b/permissions/README.rst index 7255d92f3..5146e09c1 100644 --- a/permissions/README.rst +++ b/permissions/README.rst @@ -1,6 +1,6 @@ .. _permissions: -Local Permissions +Permissions ----------------- This module implements local permissions and adds endpoints for modifying and getting permissions diff --git a/webhooks/README.rst b/webhooks/README.rst index b62fb4083..918e25a26 100644 --- a/webhooks/README.rst +++ b/webhooks/README.rst @@ -7,9 +7,9 @@ Adds endpoints for registering webhooks per project Current triggers are on commit or branch creation -Commit event: + Commit event: -.. code-block:: +:: { "projectId": "projectId", @@ -19,9 +19,9 @@ Commit event: } -Branch event: + Branch event: -.. code-block:: +:: { "projectId": "projectId", From ad43d999006ce9a0e0be589df9f785858661d155 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 14:26:17 -0800 Subject: [PATCH 21/26] Update ldap docs --- ldap/README.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/ldap/README.rst b/ldap/README.rst index 0fe6a91a6..60fe9e7a4 100644 --- a/ldap/README.rst +++ b/ldap/README.rst @@ -8,6 +8,9 @@ Adds ldap authentication provider, ldap groups the user belongs to that are also Configuration ^^^^^^^^^^^^^ + ldap.enabled + Boolean value to enable the ldap module. Required. + ldap.provider.base The base string to use. Required. From 960225bc26ab431ee6dedf401cf0cd1f63f8c3ea Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 14:30:09 -0800 Subject: [PATCH 22/26] Update localuser header --- localuser/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/localuser/README.rst b/localuser/README.rst index 80648fe39..ea4c195b9 100644 --- a/localuser/README.rst +++ b/localuser/README.rst @@ -1,6 +1,6 @@ .. _localuser: -LocalUser authentication +LocalUser ------------------------ Adds endpoint for adding local users, admins and changing password, and local authentication provider From 22fcbbcd0dff5e9e46d44b6eabb7f82523695258 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 15:17:08 -0800 Subject: [PATCH 23/26] Fix minor formatting --- webhooks/README.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/webhooks/README.rst b/webhooks/README.rst index 918e25a26..1a2234fa5 100644 --- a/webhooks/README.rst +++ b/webhooks/README.rst @@ -7,9 +7,10 @@ Adds endpoints for registering webhooks per project Current triggers are on commit or branch creation - Commit event: +Commit event +^^^^^^^^^^^^ -:: +.. code-block:: JSON { "projectId": "projectId", @@ -19,9 +20,10 @@ Current triggers are on commit or branch creation } - Branch event: +Branch event +^^^^^^^^^^^^ -:: +.. code-block:: JSON { "projectId": "projectId", From 16c097b87e52fb743c0d25fdfba60f25426a9f06 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 15:25:35 -0800 Subject: [PATCH 24/26] Add code formatting for artifacts --- artifacts/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/artifacts/README.rst b/artifacts/README.rst index 5c2aadff0..597306120 100644 --- a/artifacts/README.rst +++ b/artifacts/README.rst @@ -5,7 +5,7 @@ Artifacts Allows artifacts (binary objects) to be attached to elements. Attached artifact info are added to an element object under the ``_artifacts`` key and versioned as part of element data. -.. code-block:: +.. code-block:: JSON { "id": "elementId", @@ -26,7 +26,7 @@ Adds endpoints for getting and uploading binary content Adds ArtifactStorage interface - this allows different implementations to be used if desired given the right module -.. code-block:: +.. code-block:: java public interface ArtifactStorage { From fc8fe15e15f5d51e4ad1b0beb602654a982be0b6 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 15:27:42 -0800 Subject: [PATCH 25/26] Add code formatting for permissions --- permissions/README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/permissions/README.rst b/permissions/README.rst index 5146e09c1..99701c60b 100644 --- a/permissions/README.rst +++ b/permissions/README.rst @@ -47,7 +47,8 @@ The Permissions module provides several REST endpoints for managing permissions. For each of these endpoints, a payload must be sent with acceptable values Permissions acceptable values -:: + +.. code-block:: JSON { "users / groups": { From 3b450d5faf62767c035b55367965e2c5da105d15 Mon Sep 17 00:00:00 2001 From: Jason Han Date: Wed, 10 Feb 2021 15:42:51 -0800 Subject: [PATCH 26/26] Add reference to documentation --- crud/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crud/README.rst b/crud/README.rst index 8063a2444..31a5b230f 100644 --- a/crud/README.rst +++ b/crud/README.rst @@ -14,4 +14,4 @@ Service Factory ``defaultProjectService`` - auto creates ``master`` branch on project creation -see ``cameo`` module for ``cameoNodeService`` and ``cameoProjectService`` for an extension example for a different schema +see :ref:`cameo` module for ``cameoNodeService`` and ``cameoProjectService`` for an extension example for a different schema