Orchestrator REST Microservice#

Proof-of-concept code for PrimeQA orchestrator microservice with integration to IBM Watson Discovery and machine reading comprehension engines as a REST Server.

LICENSE|Apache2.0

✔️ Getting Started

✅ Prerequisites

  • Python 3.9

    • If you are not using a Python version manager, pyenv is highly recommended

🧩 Setup Local Environment

# Install virtualenv
pip3 install virtualenv

# Create a new virtual environment for this project. If using pyenv, path_to_python_3.9_executable will be ~/.pyenv/versions/3.9.x/bin/python
virtualenv --python=<path_to_python_3.9_executable> venv

# Activate virtual environment
source venv/bin/activate

  • Install dependencies

pip install -r requirements.txt
pip install -r requirements_test.txt

📜 TLS and Certificate Management

Orchestrator service REST server supports mutual or two-way TLS authentication (also known as mTLS).
Application config.ini file contains the default certificate paths, but they can be overridden using environment variables. All certificates are added using volume mounts on the application container. They are not shipped along with the Docker image.
Self-signed certs are added for running unit tests and local development testing. They are present in /secutiry/certs directory.
These certificates are valid for about a 100 years (until 2122) from when they were created but if you want to generate a new set of certificates, follow the steps below:

  • Navigate to /scripts directory

  • Run ./generate-certs.sh

  • When prompted for DN fields, leave everything (Country, State, Locality, Org, Unit, Email) as blank but the Common Name (CN). The fields can be left blank by just pressing Enter or return key. Use the following CNs for CA, Server and Client certificates:

    • First will be the CA certificate; use CA as the CN

    • Second will be the Server certificate; use localhost as the CN

    • Third will be the Client certificate; use Client as the CN

  • The /security/certs directory is mounted to /opt/tls on the application container and by default, the application tries to load certs from /opt/tls.

💻 Run Locally

  • Open Python IDE & set the created virtual environment

  • Open orchestrator/services/config/config.ini, set require_ssl = false (if you don’t use TLS authentication) & rest_port

  • Open application.py and run/debug

  • Go to http://localhost:{rest_port}/docs

  • Execute PATCH settings service with the primeqa.json file content

  • To be able to use all the services, be sure to have run the PrimeQA container

    • Open PrimeQA directory

    • Follow README to set it up & generate image

    • Run docker run --rm --name primeqa -d -p 50051:50051 --mount type=bind,source=/data/primeqa/store,target=/store -e STORE_DIR=/store -e mode=grpc -e require_ssl=false primeqa:$(cat VERSION)

💻 Setup & Run Docker

  • Open Dockerfile and set port

  • Open config.ini and set rest_port

  • Run docker build -f Dockerfile -t primeqa-orchestrator:$(cat VERSION) --build-arg image_version:$(cat VERSION) . (creates docker image)

  • Run docker run --rm --name primeqa_orchestrator -d -p 50059:50059 --mount type=bind,source="$(pwd)"/store,target=/store -e STORE_DIR=/store -e require_ssl=false primeqa_orchestrator:$(cat VERSION) (run docker container)

  • Go to container exposed url:port /docs

  • Execute PATCH settings service with the primeqa.json file content

  • To be able to use all the services, be sure to have run the PrimeQA container

    • Open PrimeQA directory

    • Follow README to set it up & generate image

    • Run docker run --rm --name primeqa -d -p 50051:50051 --mount type=bind,source=/data/primeqa/store,target=/store -e STORE_DIR=/store -e mode=grpc -e require_ssl=false primeqa:$(cat VERSION)

📓 Third-party dependencies

  • ColBERT repository: Please refer to ColBERT repository (specifically service branch) for more details around setting and running a local instance of NeuralIR search engine.

  • Watson Discovery: Follow instructions on IBM Cloud to configure Watson Discovery V2 service.