Commit 2c346d83 authored by ethiraj krishnamanaidu's avatar ethiraj krishnamanaidu
Browse files

Merge branch 'wdms-documentation' into 'master'

Wellbore DDMS documentation

See merge request !1
parents 55b883f3 82bce666
This diff is collapsed.
# Introduction
Wellbore Domain Data Management Services (Wellbore-DDMS) Open Subsurface Data Universe (OSDU) is one of the several backend services that comprise OSDU software ecosystem. It is a single, containerized service written in Python that provides an API for wellbore related data.
## Install Software and Packages
1. Clone the os-wellbore-ddms [repository](
2. Download [Python]( >=3.7
3. Ensure pip, a pre-installed package manager and installer for Python, is installed and is upgraded to the latest version.
# Windows
python -m pip install --upgrade pip
python -m pip --version
# macOS and Linux
python3 -m pip install --upgrade pip
python3 -m pip --version
4. Using pip, download [FastAPI](, the main framework to build the service APIs. To install fastapi and uvicorn (to work as the server), run the following command:
pip install fastapi[all]
5. [venv]( allows you to manage separate package installations for different projects. They essentially allow you to create a "virtual" isolated Python installation and packages into that virtual environment. venv is already included in the Python standard library and requires no additional installation.
### Fast API Dependencies
- [pydantic]( provides the ability to do data validation using python type annotations. It enforces type hints at runtime provide a more robust data validation option.
- [dataclasses]( module in python which provides a decorator and functions for automatically adding generated special methods to user-defined classes.
- [starlette]( lightweight ASGI framework. FastAPI is a sub-class of Starlette and includes features such as websocket support, startup and shutdown events, session and cookie support.
### Additional Dependencies
- [uvicorn]( used as ASGI server to run Wellbore-DDMS app
- [cachetools](
- [pyjwt]( and [cryptography]( for auth purposes
- [pandas]( and [numpy]( for data manipulation
- [pyarrow]( for load and save data into parquet format
- [opencensus]( for tracing and logging on cloud provider
### Library Dependencies
- Common parts and interfaces
- osdu-core-lib-python
- Implementation of blob storage on GCP
- osdu-core-lib-python-gcp
- Implementation of blob storage and partition service on Azure
- osdu-core-lib-python-azure
- Client libraries for OSDU data ecosystem services
- osdu-data-ecosystem-search
- osdu-data-ecosystem-storage
## Project Startup
### Run the service locally
1. Create virtual environment in the wellbore project directory. This will create a folder inside of the wellbore project directory. For example: ~/os-wellbore-ddms/nameofvirtualenv
# Windows
python -m venv env
# macOS/Linux
python3 -m venv env
2. Activate the virtual environment
# Windows
source env/Scripts/activate
# macOS/Linux
source env/bin/activate
5. Install dependencies
pip install -r requirements.txt
6. Run the service
# Run the service which will default to
# Run on specific host, port and enforce dev mode
python --host MY_HOST --port MY_PORT --dev_mode 1
If host is `` or `localhost`, the dev_mode is automatically set to True.
The only significant change if dev_mode is on, is that configuration errors at startup are logged but don’t prevent the service to run, and allow to override some implementations.
The hosts for the search and storage services have to be provided as environment variables, or on the command line.
### Connect and Run Endpoints
1. Generate bearer token as all APIs but `/about` require authentication.
- Navigate to ``. Click `Authorize` and enter your token. That will allow for authenticated requests.
2. Choose storage option
Even if the service runs locally it still relies on osdu data ecosystem storage service to store documents and google blob store to store binary data (`bulk data`). It is possible to override this and use your local file system instead by setting the following environment variables:
- `USE_INTERNAL_STORAGE_SERVICE_WITH_PATH` to store on a local folder instead of osdu ecosystem storage service.
- `USE_LOCALFS_BLOB_STORAGE_WITH_PATH` to store on a local folder instead of google blob storage.
# Create temp storage folders
mkdir tmpstorage
mkdir tmpblob
# Set your repo path
python -e USE_INTERNAL_STORAGE_SERVICE_WITH_PATH $path/os-wellbore-ddms/tmpstorage -e USE_LOCALFS_BLOB_STORAGE_WITH_PATH $path/os-wellbore-ddms/tmpblob
3. Choose Cloud Provider
- The code can be run with specifying environment variables and by setting the cloud provider. The accepted values are `gcp`, `az` or `local`. When a cloud provider is passed as an environment variables, there are certain additional environment variables that become mandatory.
### Setting the Cloud Provider Environment Variables
- The following environment variables are required when the cloud provider is set to GCP:
- OS_WELLBORE_DDMS_DATA_PROJECT_CREDENTIALS: path to the key file of the SA to access the data tenant
- SERVICE_HOST_SEARCH: The Search Service host
- SERVICE_HOST_STORAGE: The Storage Service host
python -e CLOUD_PROVIDER gcp \
-e SERVICE_HOST_SEARCH search_host \
-e SERVICE_HOST_STORAGE storage_host
- The following environment variables are required when the cloud provider is set to Azure:
- AZ_AI_INSTRUMENTATION_KEY: Azure Application Insights instrumentation key
- SERVICE_HOST_SEARCH: The Search Service host
- SERVICE_HOST_STORAGE: The Storage Service host
- SERVICE_HOST_PARTITION: The Partition Service internal host
- KEYVAULT_URL: The Key Vault url (needed by the Partition Service)
- USE_PARTITION_SERVICE: `enabled` when Partition Service is available in the environment. Needs to be `disabled` for `dev` or to run locally.
python -e CLOUD_PROVIDER az \
-e AZ_AI_INSTRUMENTATION_KEY instrumentationkey \
-e SERVICE_HOST_SEARCH search_host \
-e SERVICE_HOST_STORAGE storage_host \
-e SERVICE_HOST_PARTITION partition_host \
-e KEYVAULT_URL keyvault_url \
Note: If you're running locally, you may need to provide environmental variables in your IDE. Here is a sample for providing a `.env` file.
As default, all Core Services endpoint values are set to `None` in `app/`, you can update `.env` file for core services endpoints based on your cloud provider.
### Create a log record
To create a `WellLog` record, below is a payload sample for the POST `/ddms/v3/welllogs` API. The response will contain an id you can use to create some bulk data.
"acl": {
"viewers": [
"owners": [
"data": {
"Curves": [
"CurveID": "GR_ID",
"Mnemonic": "GR",
"CurveUnit": "{{datapartitionid}}:reference-data--UnitOfMeasure:m:",
"LogCurveFamilyID": "{{datapartitionid}}:reference-data--LogCurveFamily:GammaRay:"
"CurveID": "POR_ID",
"Mnemonic": "NPOR",
"CurveUnit": "{{datapartitionid}}:reference-data--UnitOfMeasure:m:",
"LogCurveFamilyID": "{{datapartitionid}}:reference-data--LogCurveFamily:NeutronPorosity:"
"CurveID": "Bulk Density",
"Mnemonic": "RHOB",
"CurveUnit": "{{datapartitionid}}:reference-data--UnitOfMeasure:m:",
"LogCurveFamilyID": "{{datapartitionid}}:reference-data--LogCurveFamily:BulkDensity:"
"WellboreID": "{{datapartitionid}}:master-data--Wellbore:{{wellboreId}}:",
"CreationDateTime": "2013-03-22T11:16:03Z",
"VerticalMeasurement": {
"VerticalMeasurement": 2680.5,
"VerticalMeasurementPathID": "{{datapartitionid}}:reference-data--VerticalMeasurementPath:MD:",
"VerticalMeasurementUnitOfMeasureID": "{{datapartitionid}}:reference-data--UnitOfMeasure:ft:"
"TopMeasuredDepth": 12345.6,
"BottomMeasuredDepth": 13856.25,
"Name": "{{welllogName}}",
"ExtensionProperties": {
"step": {
"unitKey": "ft",
"value": 0.1
"dateModified": "2013-03-22T11:16:03Z"
"id": "{{datapartitionid}}:work-product-component--WellLog:{{welllogId}}",
"kind": "osdu:wks:work-product-component--WellLog:1.0.0",
"legal": {
"legaltags": [
"otherRelevantDataCountries": [
"meta": [
"kind": "Unit",
"name": "ft",
"persistableReference": "{\"scaleOffset\":{\"scale\":0.3048,\"offset\":0.0},\"symbol\":\"ft\",\"baseMeasurement\":{\"ancestry\":\"Length\",\"type\":\"UM\"},\"type\":\"USO\"}",
"propertyNames": [
"propertyValues": [
"kind": "DateTime",
"name": "datetime",
"persistableReference": "{\"format\":\"yyyy-MM-ddTHH:mm:ssZ\",\"timeZone\":\"UTC\",\"type\":\"DTM\"}",
"propertyNames": [
### Run with Uvicorn
uvicorn app.wdms_app:wdms_app --port LOCAL_PORT
Then access app on `<LOCAL_PORT>/api/os-wellbore-ddms/docs`
### Run with Docker
#### Build Image
# Build Image
docker build -t=$IMAGE_TAG --rm . -f ./build/dockerfile --build-arg PIP_WHEEL_DIR=python-packages
#### Run Image
1. Run the image
Replace the LOCAL_PORT value with a local port
2. Access app on `<LOCAL_PORT>/api/os-wellbore-ddms/docs`
3. The environment variable `OS_WELLBORE_DDMS_DEV_MODE=1` enables dev mode
4. Logs can be checked by running
docker logs CONTAINER_ID
### Run Unit Tests Locally
# Install test dependencies
pip install -r requirements_dev.txt
python -m pytest --junit-xml=unit_tests_report.xml --cov=app --cov-report=html --cov-report=xml ./tests/unit
Coverage reports can be viewed after the command is run. The HMTL reports are saved in the htmlcov directory.
### Run Integration Tests locally
This example runs basic tests using the local filesystem for blob storage and storage service. There's no search or entilements service, everything runs locally.
First, create the temp storage folders and run the service.
mkdir -p tmpstorage
mkdir -p tmpblob
In another terminal, generate a minimum configuration file and run the integration tests.
cd tests/integration
python --token $(pyjwt --key=secret encode --base_url "" --cloud_provider "local" --data_partition "dummy"
pytest ./functional --environment="./generated/postman_environment.json" --filter-tag=basic
For more information see the [integration tests README](tests/integration/
### Port Forward from Kubernetes
1. List the pods: `kubectl get pods`
2. Port forward: `kubectl port-forward pods/POD_NAME LOCAL_PORT:8080`
3. Access it on `<LOCAL_PORT>/api/os-wellbore-ddms/docs`
### Tracing
OpenCensus libraries are used to record incoming requests metrics (execution time, result code, etc...).
At the moment, 100% of the requests are saved.
This diff is collapsed.
Markdown is supported
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