VDI Plugin Template

Table of Contents

• Usage
  • Demonstration
    • Prerequisites
    • Setup
    • Run the Example
• Creating a New Plugin Handler
  • Script Development
    • Prerequisites
    • Inputs & Outputs
    • Running Scripts Locally
    • Running Scripts in Docker

This repository is a template repo for creating new VDI plugins.

For more details about the scripts themselves and their inputs and outputs see the VDI Plugin Handler Server readme.

Usage

Demonstration

Prerequisites

• Docker

• sshuttle

Setup

1. Copy the example.env file from the root of this repo to a new file named .env in the repository root directory.
   The .env file will be ignored by Git by default.

2. Edit the new .env file by doing the following at minimum:

   1. Provide a valid LDAP_SERVER variable value.

   2. Provide a valid ORACLE_BASE_DN variable value.

   3. Provide the database TNS name and user credentials for at least one of the database configuration blocks provided.

   4. Comment out any unused database configuration blocks.

      ℹ️

      No connection to any databases will be attempted by the VDI Plugin Handler Server or any of the included example plugin scripts. The database connection details are simply required to pass server startup config validation. The TNS name is the only value that is required to be correct, the credential variables may be junk strings.

Run the Example

1. Start up sshuttle (see the VEuPathDB confluence documentation for running a service locally).

2. Start the plugin service using the start target in the included makefile.

Example

$ sshuttle ...
$ make start

Shell Access

Shell access into the plugin container can be gained quickly by using the shell target in the included makefile:

$ make shell

Shutdown

To stop the plugin service when it is no longer needed, use the stop target in the included makefile:

$ make stop

Creating a New Plugin Handler

To use this repository, click the green "Use this template" button near the top right of the repository source file listing table and create a new repository for your handler.

This repository follows the normal steps as outlined in the VEuPathDB Confluence doc titled "Deploy Containerized Services for Local Development".

Script Development

Prerequisites

• Docker

• Docker Compose Plugin

• sshuttle

Inputs & Outputs

For information about the inputs and outputs expected by the scripts, see the script documentation in the VDI Plugin Handler Readme.

Running Scripts Locally

Environment

The first step is getting an environment file set up for local execution. This can be done by first copying the included local-dev.env to a new file named .env (this file will be ignored by git). Then the new file will need to be edited to set real configuration values to replace the dummy config values.

Depending on the script you are developing and its requirements, some of the following variables may not be necessary, but in the service environment all scripts are provided the following set of environment variables in addition to their CLI inputs.

PROJECT_ID=PlasmoDB
DB_HOST=SomeAppDBHost
DB_PORT=1521
DB_NAME=SomeAppDBName (name.site.com)
DB_USER=SomeAppDBUser
DB_PASS=SomeAppDBPassword
DB_PLATFORM=Oracle

When running the scripts outside of Docker, these values will need to be set in your environment. This may be easily done by sourcing the .env file after it has been edited.

$ source .env

Execution

1. Start sshuttle

2. Source the local-dev.env file.

3. Run the target plugin script.

Running Scripts in Docker

As the plugin scripts require file inputs, the easiest way to test them in a running container is to copy the files into the container for initial development or testing purposes. This is done by applying a temporary change to the Dockerfile to add a line for copying the test data into the image.

COPY testdata/ /opt/veupathdb/testdata

This Dockerfile change should be removed before the plugin is ready to be released.

Execution

Startup

1. Add any necessary testing changes to the Dockerfile.

2. Rebuild the docker image by running make build

3. Tunnel into a new temporary container by running make shell

From there you should be able to execute your plugin scripts via the bash command line.