Deployment Guide

The ColabBio Base Platform embraces a “3 Levels of Deployment” philosophy, allowing you to scale seamlessly from local development to production-grade sovereign clusters.

3 Levels of Deployment

Level 1: Local / Edge (Docker Compose)

Designed for rapid development of Go adapters, UI testing, and unit testing pipelines.

• Profiles: Pre-configured Docker Compose profiles such as ohdsi, omero, and load.
• Usage:

  # Deploy the OHDSI stack (Atlas + WebAPI) locally
  docker compose --profile ohdsi up -d

Level 2: Hospital Cluster (MicroK8s + Skaffold + Helm)

The primary deployment mode for hospital on-premise infrastructure. It uses MicroK8s as the engine, orchestrated by Skaffold and Helm.

• Profiles: dev, stage, prod.
• Usage:

  # Deploy a staging environment to the cluster
  skaffold run --profile stage

Level 3: Cloud IaC (Terraform)

For large pharma or centralized data nodes, ColabBio provides Terraform modules to deploy on managed cloud services like GKE and Cloud SQL.

• Usage:

  terraform init
  terraform plan
  terraform apply

Advanced: Automated VM Bootstrap (Edge Node)

If you are provisioning a clean Ubuntu 22.04+ Virtual Machine (either locally or on a cloud provider), the platform provides an automated bootstrap script cb-devops/scripts/colabbio-node-init.sh.

This script converts a bare VM into a fully operational ColabBio Edge Node:

• Installs MicroK8s, system dependencies, and enables necessary addons (dns, helm3, storage).
• Supports mesh network configuration with Tailscale to interconnect multiple VMs.
• Configures NFS automatically to share volumes across nodes.
• Supports provisioning a master node (--role master), a normal worker (--role worker), or an NVIDIA GPU worker (--role gpu-worker).

# Example execution on a clean VM
sudo ./colabbio-node-init.sh --role master --namespace colabbio-dev --chart-path ../cluster/charts/rwe-stack

Prerequisites

Depending on your target deployment level, you will need:

• Docker: >= 24.0 (with compose plugin >= 2.20) for Level 1.
• MicroK8s: >= 1.29 (with dns, storage, ingress, and helm3 enabled) for Level 2.
• Skaffold: >= 2.10
• Helm: >= 3.14

Secrets Management

ColabBio enforces strict security boundaries based on the environment:

• Development: Credentials can be managed in plain text inside docker-compose.yml for speed and simplicity.
• Staging / Production: Credentials must be injected via Kubernetes Secrets. The Helm charts automatically reference existingSecret: colabbio-db-secrets based on the Skaffold profile values.

# Example: Creating a production secret
kubectl create secret generic colabbio-db-secrets \
  --namespace colabbio-prod \
  --from-literal=OMOP_POSTGRES_PASSWORD=<strong-password>