Skip to content
Snippets Groups Projects
Commit df0d31e2 authored by Chad Leong's avatar Chad Leong :speech_balloon:
Browse files

Documentation update with mkdocs

parent ecc4a95a
No related branches found
No related tags found
1 merge request!494Documentation update with mkdocs
Pipeline #250666 failed
Stage: review
Stage: build
Stage: publish
Stage: deploy
Expand all Hide whitespace changes
Inline Side-by-side
.gitlab-ci.yml
+ 139
− 140
View file @ df0d31e2
variables:
AWS_BUILD_SUBDIR: provider/notification-aws/build-aws
AWS_TEST_SUBDIR: testing/notification-test-aws
AWS_CHART_SUBDIR: devops/aws/chart
AWS_SERVICE: notification
AWS_SERVICE_GATEWAY: osdu-gateway
AWS_ENVIRONMENT: dev
AWS_DEPLOY_TARGET: TF
AWS_EKS_DEPLOYMENT_NAME: os-notification
AZURE_SERVICE: notification
AZURE_BUILD_SUBDIR: provider/notification-azure
AZURE_TEST_SUBDIR: testing/notification-test-azure
AZURE_DEPLOYMENTS_SUBDIR: deployments/scripts/azure
AZURE_COVERAGE_THRESHOLD: 80
IBM_BUILD_SUBDIR: provider/notification-ibm
IBM_INT_TEST_SUBDIR: testing/notification-test-ibm
IBM_HELM_CONFIG_PATH: devops/ibm/ibm-notification-config
IBM_HELM_DEPLOY_PATH: devops/ibm/ibm-notification-deploy
AWS_BUILD_SUBDIR: provider/notification-aws/build-aws
AWS_TEST_SUBDIR: testing/notification-test-aws
AWS_CHART_SUBDIR: devops/aws/chart
AWS_SERVICE: notification
AWS_SERVICE_GATEWAY: osdu-gateway
AWS_ENVIRONMENT: dev
AWS_DEPLOY_TARGET: TF
AWS_EKS_DEPLOYMENT_NAME: os-notification
AZURE_SERVICE: notification
AZURE_BUILD_SUBDIR: provider/notification-azure
AZURE_TEST_SUBDIR: testing/notification-test-azure
AZURE_DEPLOYMENTS_SUBDIR: deployments/scripts/azure
AZURE_COVERAGE_THRESHOLD: 80
IBM_BUILD_SUBDIR: provider/notification-ibm
IBM_INT_TEST_SUBDIR: testing/notification-test-ibm
IBM_HELM_CONFIG_PATH: devops/ibm/ibm-notification-config
IBM_HELM_DEPLOY_PATH: devops/ibm/ibm-notification-deploy
include:
- project: "osdu/platform/ci-cd-pipelines"
file: "standard-setup.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "standard-setup.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "build/maven.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "build/maven.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "scanners/fossa-maven.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "scanners/fossa-maven.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "scanners/gitlab-ultimate.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "scanners/gitlab-ultimate.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "cloud-providers/azure.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "cloud-providers/azure.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "cloud-providers/gc-global.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "cloud-providers/gc-global.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "cloud-providers/ibm.yml"
- project: "osdu/platform/ci-cd-pipelines"
file: "cloud-providers/ibm.yml"
# aws
- local: "devops/aws/pipeline/override-stages.yml"
# aws
- local: "devops/aws/pipeline/override-stages.yml"
- local: "devops/gc/pipeline/override-stages.yml"
- local: "devops/gc/pipeline/override-stages.yml"
- local: "/publish.yml"
.maven:
image: maven:3.9.3-eclipse-temurin-17
tags: ['osdu-medium']
variables:
MAVEN_REPO_PATH: "$CI_PROJECT_DIR/.m2/repository"
MAVEN_CLI_OPTS: "--batch-mode --settings=$CI_PROJECT_DIR/.mvn/community-maven.settings.xml"
cache:
paths:
- $MAVEN_REPO_PATH
artifacts:
paths:
- ./**/target/*.jar
- ./**/maven-*-output.txt
when: always
expire_in: 2 days
before_script:
- | # Check for the presence of a maven wrapper script
apt-get update && apt-get install -y python3
if [ -e "$CI_PROJECT_DIR/mvnw" ]; then
export MAVEN_BINARY="$CI_PROJECT_DIR/mvnw"
unset MAVEN_CONFIG
mkdir -pv .mvn/wrapper
else
export MAVEN_BINARY="mvn"
fi
- export MAVEN="$MAVEN_BINARY $MAVEN_CLI_OPTS -Dmaven.repo.local=$MAVEN_REPO_PATH"
- echo $MAVEN_BINARY
- echo $MAVEN_CLI_OPTS
- echo $MAVEN_REPO_PATH
- echo $MAVEN
- mkdir -pv $MAVEN_REPO_PATH
- export ALL_MAVEN_BUILD_DIRS_Z=$(mktemp)
- python3 --version
# This scans for all pom.xml files that aren't listed as a child pom (as
# determine by the presence of a <parent> tag).
- |
(python3 | sort -z > $ALL_MAVEN_BUILD_DIRS_Z) <<EOF
from xml.dom.minidom import parse
import os
import sys
allPomFiles = set()
submoduleFiles = set()
for root, dirnames, filenames in os.walk(os.environ['CI_PROJECT_DIR']):
if 'pom.xml' in filenames:
pomFile = os.path.join(root, 'pom.xml')
allPomFiles.add(pomFile)
dom = parse(pomFile)
for modules in dom.getElementsByTagName('modules'):
for module in modules.getElementsByTagName('module'):
submoduleFiles.add(os.path.join(root, module.firstChild.nodeValue, "pom.xml"))
for pomFile in allPomFiles:
if pomFile not in submoduleFiles:
dir = os.path.dirname(pomFile)
sys.stdout.write(dir + '\0')
EOF
- xargs -0rn 1 echo < $ALL_MAVEN_BUILD_DIRS_Z
# This creates a script for running maven, capturing output to a file.
# - First argument is the directory to build from
# - Second argument is the name to use for the logfile
# - The remaining arguments are the maven command to run
- export MAVEN_BUILD=$(tempfile -m 755 -p build -s .sh)
- echo "#!/bin/bash" > $MAVEN_BUILD
- |
cat >> $MAVEN_BUILD <<EOF
id=maven_build_\$(echo "\$@" | sha1sum | head -c 7)
cd "\$1"; shift
outputFile="\$1"; shift
echo "********************************************************************************"
echo -e "\e[0Ksection_start:\$(date +%s):\${id}\r\e[0K\e[1m\$(pwd)\e[0m"
echo -e "\e[32;1m\$MAVEN" "\$@" "\e[0m"
if \$MAVEN "\$@" > "\$outputFile" 2>&1; then
tail -n 25 "\$outputFile";
echo -e "\e[36m**** Showing the last 25 lines of the passed build (above). See Job artifacts for full log details *****\e[0m";
echo -e "\e[0Ksection_end:\$(date +%s):\${id}\r\e[0K"
else
tail -n 200 "\$outputFile";
echo -e "\e[31m**** Showing the last 200 lines of the failed build (above). See Job artifacts for full log details *****\e[0m";
echo -e "\e[0Ksection_end:\$(date +%s):\${id}\r\e[0K"
exit 255;
fi
EOF
# This creates a script for applying the $MAVEN_BUILD script to all build directories
- export MAVEN_FOREACH=$(tempfile -m 755 -p fr-ec -s .sh)
- echo "#!/bin/sh" > $MAVEN_FOREACH
- echo 'xargs -0rI {} $MAVEN_BUILD {} "$@" < $ALL_MAVEN_BUILD_DIRS_Z' >> $MAVEN_FOREACH
image: maven:3.9.3-eclipse-temurin-17
tags: ["osdu-medium"]
variables:
MAVEN_REPO_PATH: "$CI_PROJECT_DIR/.m2/repository"
MAVEN_CLI_OPTS: "--batch-mode --settings=$CI_PROJECT_DIR/.mvn/community-maven.settings.xml"
cache:
paths:
- $MAVEN_REPO_PATH
artifacts:
paths:
- ./**/target/*.jar
- ./**/maven-*-output.txt
when: always
expire_in: 2 days
before_script:
- | # Check for the presence of a maven wrapper script
apt-get update && apt-get install -y python3
if [ -e "$CI_PROJECT_DIR/mvnw" ]; then
export MAVEN_BINARY="$CI_PROJECT_DIR/mvnw"
unset MAVEN_CONFIG
mkdir -pv .mvn/wrapper
else
export MAVEN_BINARY="mvn"
fi
- export MAVEN="$MAVEN_BINARY $MAVEN_CLI_OPTS -Dmaven.repo.local=$MAVEN_REPO_PATH"
- echo $MAVEN_BINARY
- echo $MAVEN_CLI_OPTS
- echo $MAVEN_REPO_PATH
- echo $MAVEN
- mkdir -pv $MAVEN_REPO_PATH
- export ALL_MAVEN_BUILD_DIRS_Z=$(mktemp)
- python3 --version
# This scans for all pom.xml files that aren't listed as a child pom (as
# determine by the presence of a <parent> tag).
- |
(python3 | sort -z > $ALL_MAVEN_BUILD_DIRS_Z) <<EOF
from xml.dom.minidom import parse
import os
import sys
allPomFiles = set()
submoduleFiles = set()
for root, dirnames, filenames in os.walk(os.environ['CI_PROJECT_DIR']):
if 'pom.xml' in filenames:
pomFile = os.path.join(root, 'pom.xml')
allPomFiles.add(pomFile)
dom = parse(pomFile)
for modules in dom.getElementsByTagName('modules'):
for module in modules.getElementsByTagName('module'):
submoduleFiles.add(os.path.join(root, module.firstChild.nodeValue, "pom.xml"))
for pomFile in allPomFiles:
if pomFile not in submoduleFiles:
dir = os.path.dirname(pomFile)
sys.stdout.write(dir + '\0')
EOF
- xargs -0rn 1 echo < $ALL_MAVEN_BUILD_DIRS_Z
# This creates a script for running maven, capturing output to a file.
# - First argument is the directory to build from
# - Second argument is the name to use for the logfile
# - The remaining arguments are the maven command to run
- export MAVEN_BUILD=$(tempfile -m 755 -p build -s .sh)
- echo "#!/bin/bash" > $MAVEN_BUILD
- |
cat >> $MAVEN_BUILD <<EOF
id=maven_build_\$(echo "\$@" | sha1sum | head -c 7)
cd "\$1"; shift
outputFile="\$1"; shift
echo "********************************************************************************"
echo -e "\e[0Ksection_start:\$(date +%s):\${id}\r\e[0K\e[1m\$(pwd)\e[0m"
echo -e "\e[32;1m\$MAVEN" "\$@" "\e[0m"
if \$MAVEN "\$@" > "\$outputFile" 2>&1; then
tail -n 25 "\$outputFile";
echo -e "\e[36m**** Showing the last 25 lines of the passed build (above). See Job artifacts for full log details *****\e[0m";
echo -e "\e[0Ksection_end:\$(date +%s):\${id}\r\e[0K"
else
tail -n 200 "\$outputFile";
echo -e "\e[31m**** Showing the last 200 lines of the failed build (above). See Job artifacts for full log details *****\e[0m";
echo -e "\e[0Ksection_end:\$(date +%s):\${id}\r\e[0K"
exit 255;
fi
EOF
# This creates a script for applying the $MAVEN_BUILD script to all build directories
- export MAVEN_FOREACH=$(tempfile -m 755 -p fr-ec -s .sh)
- echo "#!/bin/sh" > $MAVEN_FOREACH
- echo 'xargs -0rI {} $MAVEN_BUILD {} "$@" < $ALL_MAVEN_BUILD_DIRS_Z' >> $MAVEN_FOREACH
gemnasium-maven-dependency_scanning:
variables:
DS_JAVA_VERSION: 17
variables:
DS_JAVA_VERSION: 17
azure_containerize:
variables:
AZURE_CONTAINERIZE_REPOSITORY: "-b jdk-17 https://gitlab-ci-token:${CI_JOB_TOKEN}@community.opengroup.org/osdu/platform/deployment-and-operations/base-containers-azure/service-base-image"
variables:
AZURE_CONTAINERIZE_REPOSITORY: "-b jdk-17 https://gitlab-ci-token:${CI_JOB_TOKEN}@community.opengroup.org/osdu/platform/deployment-and-operations/base-containers-azure/service-base-image"
azure_test:
image: community.opengroup.org:5555/osdu/platform/deployment-and-operations/base-containers-azure/azure-maven17:v0.0.1
image: community.opengroup.org:5555/osdu/platform/deployment-and-operations/base-containers-azure/azure-maven17:v0.0.1
fossa-analyze:
image: $CI_REGISTRY/divido/fossa-with-cache:v0.9-jdk17
image: $CI_REGISTRY/divido/fossa-with-cache:v0.9-jdk17
fossa-check-notice:
image: $CI_REGISTRY/divido/fossa-with-cache:v0.9-jdk17
image: $CI_REGISTRY/divido/fossa-with-cache:v0.9-jdk17
README.md
+ 17
− 13
View file @ df0d31e2
......@@ -12,20 +12,24 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
# Notification service
# Register service
The Notification service, with Register service, allow interested consumers to subscribe to data and metadata changes using a publisher/subscriber pattern
## Documentation
Official documentation home for [Notification Service](https://osdu.pages.opengroup.org/platform/system/notification/)
## Dependencies needed to run the code locally
* JDK11
* Maven
* Azure Devops access to slb-des-ext-collaboration organization. You need to generate a PAT that can access dependencies held in the Azure artifacts
* Working Register service endpoint
- JDK11
- Maven
- Azure Devops access to slb-des-ext-collaboration organization. You need to generate a PAT that can access dependencies held in the Azure artifacts
- Working Register service endpoint
## Build and run service locally
* Build the service and run the unit tests. This step also generates the executable jar file. Run this command from the root folder, where parent pom.xml resides
- Build the service and run the unit tests. This step also generates the executable jar file. Run this command from the root folder, where parent pom.xml resides
**Note**: At runtime, you must set a Spring profile so the right runtime configuration gets picked up for your app. Since this is a Spring Boot application, runtime configuration is defined in one of the application properties files under `<provider>->src->main->resources`. You can set the right Spring Boot runtime profile with `-Dspring.profiles.active=test`. Please read [this](https://stackoverflow.com/questions/39738901/how-do-i-activate-a-spring-boot-profile-when-running-from-intellij) for more info.
......@@ -33,23 +37,23 @@ The Notification service, with Register service, allow interested consumers to s
mvn clean install
```
* To run the service locally, navigate to `provider/notification-<your_provider>/target` directory and execute the spring-boot jar
- To run the service locally, navigate to `provider/notification-<your_provider>/target` directory and execute the spring-boot jar
```
java -jar notification-gc-1.0.0-spring-boot.jar
```
* To debug service locally, create a remote debug configuration first and then use following command to start service in debug mode
- To debug service locally, create a remote debug configuration first and then use following command to start service in debug mode
```
java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n -jar notification-gc-1.0.0-spring-boot.jar
```
**Note:** The port number "8000" in the command should match with the remote debug config settings.
**Note:** The port number "8000" in the command should match with the remote debug config settings.
## Access the service
The port and path for the service endpoint can be configured in ```application.properties``` as following. If not specified, then the web container (ex. Tomcat) default is used:
The port and path for the service endpoint can be configured in `application.properties` as following. If not specified, then the web container (ex. Tomcat) default is used:
```bash
server.servlet.contextPath=/
......@@ -57,6 +61,7 @@ server.port=8080
```
## Open API 3.0 - Swagger
- Swagger UI : https://host/context-path/swagger (will redirect to https://host/context-path/swagger-ui/index.html)
- api-docs (JSON) : https://host/context-path/api-docs
- api-docs (YAML) : https://host/context-path/api-docs.yaml
......@@ -64,12 +69,11 @@ server.port=8080
All the Swagger and OpenAPI related common properties are managed here [swagger.properties](./notification-core/src/main/resources/swagger.properties)
#### Server Url(full path vs relative path) configuration
- `api.server.fullUrl.enabled=true` It will generate full server url in the OpenAPI swagger
- `api.server.fullUrl.enabled=false` It will generate only the contextPath only
- default value is false (Currently only in Azure it is enabled)
[Reference]:(https://springdoc.org/faq.html#_how_is_server_url_generated)
# new update
[Reference]:(https://springdoc.org/faq.html#_how_is_server_url_generated)
## AWS
......
docs/mkdocs.yml 0 → 100644
+ 38
− 0
View file @ df0d31e2
site_name: OSDU Notification Documentation
site_description: OSDU Notification Service
site_author: Chad Leong [SLB]
# Repository
repo_url: https://community.opengroup.org/osdu/platform/system/notification
repo_name: notification
# Copyright
copyright: Copyright &copy; 2024 Open Subsurface Data Universe Software
theme:
name: material
palette:
- scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/brightness-7
name: Switch to dark mode
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
name: Switch to light mode
font:
text: Roboto
code: Roboto Mono
markdown_extensions:
- admonition
- sane_lists
- tables
plugins:
- search
- git-revision-date
publish.yml 0 → 100644
+ 30
− 0
View file @ df0d31e2
run-test-pages:
stage: build
image: python:latest
script:
- cd docs
- pip install mkdocs-material
- pip install mkdocs-git-revision-date-plugin
- mkdocs build --site-dir ../test
allow_failure: true
artifacts:
paths:
- test
when: manual
pages:
stage: publish
image: python:latest
tags: ["osdu-medium"]
script:
- cd docs
- pip install --default-timeout=1000 mkdocs-material
- pip install mkdocs-git-revision-date-plugin
- mkdocs build --site-dir ../public
allow_failure: true
needs: []
artifacts:
paths:
- public
# rules:
# - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment