= VEuPathDB Dataset Installer Service (VDI) :source-highlighter: highlightjs :toc:

ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

ifndef::env-github[] :icons: font endif::[]

== Tagging, Deployment, and Branch Rules

=== Branch Rules

==== qa

The qa branch is to reflect what is currently on QA. Code may only be pushed to this branch via pull request which depends on both approval and a successful workflow build of the code.

==== production

The production branch should always reflect what is on production. This branch is to remain locked until we are ready to move code from QA to production, at which point the following steps will be performed:

. The production branch will be unlocked via the repository settings. . The qa branch will be merged into production . The production branch will be re-locked via the repository settings.

[IMPORTANT]

These steps are not the service deployment steps, they are simply an outline of steps strictly related to getting the production branch up to date with the qa branch. For deployment procedure steps see the <> section below.

==== main

The main branch is for active development. It is strongly advised that fixes and features be developed on branches forked from main and then merged back into main when complete to avoid conflict problems with other active development.

=== Tagging

Release tags v* are only to be made on the production branch.

Other tags should be avoided.

=== Deployment

The following is a full list of steps necessary to perform a deployment of the QA VDI service code onto production.

. Unlock the production branch via the repository settings. This setting can be found in the "Branches" menu under the "production" branch rule. The specific setting to uncheck is "Lock Branch". . Merge the qa branch into production. . Re-lock the production branch via the setting described in step 1. . Wait for the production branch to build in Jenkins. . Create a new release tag on the merge commit from qa to production. . Wait for the new tag to build in Jenkins. . Create a PR on the https://github.com/VEuPathDB/tagger[Tagger] repository, forked from and targeting the prod branch, updating the vdi-service tag to the new tag created in step 5. . Assign the PR to systems and notify them of the PR.

[WARNING]

Steps 4 and 6 are necessary to avoid known issues with our current Jenkins build setup for containerized services.

== Links

=== Documentation

• link:https://veupathdb.github.io/vdi-service/vdi-api.html[VDI Service API Doc]
• link:https://veupathdb.github.io/vdi-service/design/1.0/design.html[Service Design Doc]
• link:https://veupathdb.atlassian.net/wiki/spaces/UI/pages/36438144/VDI+User+Datasets+Design[Original Design Doc]
• link:docs/env-vars.adoc[Environment Config Doc]
• link:docs/local-dev-readme.adoc[Local Development Doc]

=== VDI Project Index

==== Services

• https://github.com/VEuPathDB/vdi-service[VDI Core Service]
• https://github.com/VEuPathDB/vdi-plugin-handler-server[VDI Plugin Handler Service]

==== Docker Images

• https://github.com/VEuPathDB/vdi-internal-db[Cache DB Docker Image]
• https://github.com/VEuPathDB/vdi-docker-handler-base[Plugin Handler Base]

==== Libraries

===== Service Libraries

• https://github.com/VEuPathDB/vdi-component-common[Commons Library]
• https://github.com/VEuPathDB/vdi-component-json[JSON Utilities]

===== Plugin Libraries

• https://github.com/VEuPathDB/lib-vdi-plugin-rnaseq[lib-rnaseq]
• https://github.com/VEuPathDB/lib-vdi-plugin-study[lib-study]

==== Plugins

===== Production

• https://github.com/VEuPathDB/vdi-plugin-bigwig[bigwig]
• https://github.com/VEuPathDB/vdi-plugin-biom[biom]
• https://github.com/VEuPathDB/vdi-plugin-isasimple[isasimple]
• https://github.com/VEuPathDB/vdi-plugin-rnaseq[rnaseq]
• https://github.com/VEuPathDB/vdi-plugin-genelist[genelist]

===== Examples

• https://github.com/VEuPathDB/vdi-handler-plugin-example[Example Plugin]

== Repo Structure

The VDI service repository is divided into 4 categories: components, daemons, lanes, and the core bootstrapper.

Components are small shared libraries that contain code specific to a purpose that is not the core focus of the VDI service.

Daemons are background processes that perform maintenance tasks such as dataset reconciliation or pruning old, soft-deleted datasets from S3.

Lanes are event handlers that are tailored to individual event types, performing some process or processes on a dataset specified in the subscribed events.

The bootstrapper is the core of the service, and the root level Gradle project. This piece is responsible for starting up and shutting down the various project modules.

=== Internal Libs

Shared library components used by one or more VDI daemons, lanes, the rest service, and/or the bootstrapper.

• link:lib/app-db/[App DB Client]
• link:lib/async/[Async Utilities]
• link:lib/install-cleanup/[Broken Install Cleanup]
• link:lib/cache-db/[Cache DB Client]
• link:https://github.com/VEuPathDB/vdi-component-common[Commons]
• link:lib/pruner[Dataset Pruner]
• link:lib/dataset-reinstaller/[Dataset Reinstaller]
• link:https://github.com/VEuPathDB/vdi-component-json[JSON Utilities]
• link:lib/kafka[Kafka Client]
• link:lib/ldap[LDAP Utilities]
• link:lib/module-core/[Module Core]
• link:lib/plugin-client[Plugin Server Client]
• link:lib/plugin-mapping[Plugin Mapping]
• link:lib/rabbit[Rabbit Client]
• link:lib/s3[S3 Utilities]
• link:lib/env/[Shared Env Constants & Utilities]
• link:lib/test-utils[Unit Test Utilities]

=== Daemons

Background tasks that run unsupervised.

• link:service/daemon/dataset-reinstaller/[Dataset Reinstaller]
• link:service/daemon/event-router/[Event Router]
• link:service/daemon/pruner/[Pruner]
• link:service/daemon/reconciler/[Reconciler]

=== Lanes

Dataset event handlers. Each lane is a separate process that subscribes to a Kafka channel and operates on datasets whose information is provided in the incoming events.

• link:service/lane/hard-delete/[Hard Delete Event Handler]
• link:service/lane/import/[Import Event Handler]
• link:service/lane/install/[Install Data Event Handler]
• link:service/lane/reconciliation/[Reconciliation Event Handler]
• link:service/lane/sharing/[Share Event Handler]
• link:service/lane/soft-delete/[Soft Delete Event Handler]
• link:service/lane/update-meta/[Update Meta Event Handler]

=== Rest Service

The rest service is the public API through which users and administrators communicate with and operate on the VDI system.

• link:service/rest-service/[Rest API Service]

=== Bootstrapper

The bootstrapper is the core of the service, and the root level Gradle project. This piece is responsible for starting up and shutting down the various project modules.

• link:service/bootstrap/[Bootstrapper]

== Development

=== Running the Stack

. make build + Builds the VDI service docker image. . make up + Spins up the service. . make down + Shuts down the service and removes all the vdi-specific containers, volumes, and networks.