About Bio-OS

Bio-OS is an open-source platform for genomics users. It provides a workspace which encapsulates data, workflows, Notebooks, job history, etc. Bio-OS provides both GUI and CLI(Command Line Interface) to quickly setup and run workflows specified by languages like WDL and notebook as well.

Bio-OS Concept

Bio-OS Workspace

Workspace is a complete encapsulation of a bioinformatics research process, including data, environment, code, operational calculation procedures, results, and dashboard as an overview. It is the basic unit that realizes executable, transportable, reproducible, shareable and publishable scientific research and biological application.

Architecture :

In Bio-OS, there are three parts in the architecture.

Control layer:

1. Bioos-web: the front-end component of Bio-OS.
2. Bioctl is the command-line component of Bio-OS. Users can access Bio-OS through bioctl.
3. OpenAPI is used to describe, produce, consume, and visualize RESTful web services. It's a specification standard for REST APIs that defines the structure and syntax.
4. Bioos-apiserver: It mainly realizes the management of workspace, workflow (conforming to WES specification), data, etc. The bioos-server will send requests to the clusters of each computing plane to implement the running workflow
5. IAM(not supported in Version 1.0.0): service that helps you securely control user access

Workflow Layer

1. Cromwell: open-source cromwell version v85
2. Storage : store workflow input ,output data or log

Notebook Layer

1. JupyterHub: a multi-user Hub that spawns, manages, and proxies multiple instances of the single-user Jupyter notebook server.
2. Storage : Used to store data from jupyter notebook

Capabilities

There are four core capabilities which support Bio-OS. - Data Management

Effectively organize massive scale sample data and easily access public data

• Application Management

Bring together data、workflow、Notebooks、work engine into Sharable、 Traceable and reproducible Workspace

• Resource Management

Autoscaling through cloud-native which supports hybrid scheduling of multi-cloud heterogeneous resources

• Interactive Analysis

Using Built-in Notebook to do tertiary analysis

Getting Started

Prerequisites

To run Bio-OS, the following prerequisites must be met: - A computer with one of the following operating systems: - CentOS 7.9 + - Ubuntu 22.04 + - Internet access - Resource Required

Minimum 8 cpu and 16G memory

Installation

There will be two ways to install Bio-OS . 1. Using Docker-compose

• cromwell deployment

Bio-OS V1.0.0 Version does not support cromwell containerized deployment，You need to install java-jre 11 version on the server and configure application.conf.

include required(classpath("application"))
webservice {
  port = 8000
}
workflow-options {
  workflow-log-dir = /nfs/bioos-storage/cromwell-workflow-logs
  workflow-log-temporary = false
}
call-caching {
  enabled = true
  invalidate-bad-cache-results = true
}
database {
  profile = "slick.jdbc.MySQLProfile$"
  db {
    driver = "com.mysql.cj.jdbc.Driver"
    url = "jdbc:mysql://180.184.37.106:3306/wqw?rewriteBatchedStatements=true&useSSL=false"
    port = 3306
    user = "public"
    password = "Mirrors79"
    connectionTimeout = 5000
  }
}
backend {
  default = "Local"
  providers {
    Local {
      config {
        root = "/nfs/bioos-storage/cromwell-executions"
        filesystem {
          local {
           localization: [
                  "hard-link", "soft-link", "copy"
           ]

            caching {
              duplication-strategy: [
                "hard-link", "soft-link", "copy"
              ]
              hashing-strategy: "md5"
              check-sibling-md5: false
            }
          }
        }
      }
    }
  }
}

Attention: The workflow-log-dir configuration should be consistent with the apiserver reference storage configuration. Execute the following code to complete the cromwell local deployment, and the apiserver in the subsequent docker-compose.yaml will refer to the cromwell call.

java -jar -Dconfig.file=/root/cromwell/application.conf -DLOG_LEVEL=INFO -DLOG_MODE=standard /root/cromwell/cromwell.jar server

• Bioos local startup

For local container environment testing, you need to install the docker container environment. Our code base provides the'docker-compose.yaml 'file.

Local environment testing can be quickly completed with the following commands.

# 进入开源 bioos 目录,执行命令
docker-compose up -d

Note: Local deployment will involve the problem of jupyterhub dynamically obtaining tokens. You can refer to the online deployment part. To update the token, you need to restart the bioos-apiserver container.

1. Online Deployment

Online deployment requires the preparation of a container orchestration engine, and we provide helm deployment packages to quickly complete bioos deployment.

• Deployment based on Kubernetes environment

If there is no local Kubernetes environment, you can try to deploy minikube. For details, please refer to the official website.

When installing the container runtime, you have two options: - Docker - The most common container runtime environment - Deployment method shell sudo apt update && apt install docker.io -y - Nerdctl - Open source and open operating environment, a perfect alternative to the cncf community - Deployment method shell wget https://github.com/containerd/nerdctl/releases/download/v1.4.0/nerdctl-full-1.4.0-linux-amd64.tar.gz tar zxf nerdctl-full-1.4.0-linux-amd64.tar.gz -C /usr/local/ cp /usr/local/lib/systemd/system/*.service /etc/systemd/system/ ln -s /usr/local/bin/nerdctl /usr/bin/docker systemctl enable buildkit containerd systemctl restart buildkit containerd Kubernetes environment also has many deployment methods, common deployment forms such as minikube/microk8s/kubeadm/kubespray, considering the simplicity and ease of use, here take minikube as an example to build the local environment, production environment recommends choosing kubespray for high availability deployment.

# 安装基础依赖
sudo apt update && apt install -y conntrack
sudo sysctl fs.protected_regular=0 #重启之后，记得执行一下，避免 minikube /tmp/juju-mkf6a06118463380f4d96c12aced04598f450743: permission denied 类似报错
mkdir -p /etc/containerd && containerd config default >  /etc/containerd/config.toml
wget https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.27.0/crictl-v1.27.0-linux-amd64.tar.gz
tar xvf crictl-v1.27.0-linux-amd64.tar.gz -C /usr/bin/
# 安装 minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
# 使用国内源安装 kubernetes
minikube start \
--container-runtime="containerd" \
--image-mirror-country=cn \
--image-repository=registry.cn-hangzhou.aliyuncs.com/google_containers \
--driver=none \
--apiserver-ips='xxx.xxx.xx.xx' # 可选配置，如果需要外网访问，需要这里配置主机的外网IP

Deployment log information:

root@registry:/home/vagrant# minikube start --container-runtime="containerd" --image-mirror-country=cn --driver=none --image-repository=registry.cn-hangzhou.aliyuncs.com/google_containeres
😄  minikube v1.30.1 on Ubuntu 22.04 (amd64)
✨  Using the none driver based on existing profile
❗  Using the 'containerd' runtime with the 'none' driver is an untested configuration!
❗  Using the 'containerd' runtime with the 'none' driver is an untested configuration!
👍  Starting control plane node minikube in cluster minikube
🔄  Restarting existing none bare metal machine for "minikube" ...
ℹ️  OS release is Ubuntu 22.04.1 LTS
📦  Preparing Kubernetes v1.26.3 on containerd 1.6.12-0ubuntu1 ...
▪ kubelet.resolv-conf=/run/systemd/resolve/resolv.conf
> kubectl.sha256:  64 B / 64 B [-------------------------] 100.00% ? p/s 0s
> kubeadm.sha256:  64 B / 64 B [-------------------------] 100.00% ? p/s 0s
> kubelet.sha256:  64 B / 64 B [-------------------------] 100.00% ? p/s 0s
> kubectl:  45.81 MiB / 45.81 MiB [-------------] 100.00% 5.61 MiB p/s 8.4s
> kubeadm:  44.61 MiB / 44.61 MiB [--------------] 100.00% 2.27 MiB p/s 20s
> kubelet:  115.65 MiB / 115.65 MiB [------------] 100.00% 4.39 MiB p/s 27s
▪ Generating certificates and keys ...
▪ Booting up control plane ...
▪ Configuring RBAC rules ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🤹  Configuring local host environment ...

❗  The 'none' driver is designed for experts who need to integrate with an existing VM
💡  Most users should use the newer 'docker' driver instead, which does not require root!
📘  For more information, see: https://minikube.sigs.k8s.io/docs/reference/drivers/none/

❗  kubectl and minikube configuration will be stored in /root
❗  To use kubectl or minikube commands as your own user, you may need to relocate them. For example, to overwrite your own settings, run:

    ▪ sudo mv /root/.kube /root/.minikube $HOME
    ▪ sudo chown -R $USER $HOME/.kube $HOME/.minikube

💡  This can also be done automatically by setting the env var CHANGE_MINIKUBE_NONE_USER=true
▪ Using image registry.cn-hangzhou.aliyuncs.com/google_containers/storage-provisioner:v5
🔎  Verifying Kubernetes components...
🌟  Enabled addons: default-storageclass, storage-provisioner
💡  kubectl not found. If you need it, try: 'minikube kubectl -- get pods -A'
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

After installing minikube, we still need to do some small configuration, such as configuring network plugins

# 追加 kubectl  快捷方式
echo 'alias kubectl="minikube kubectl --"' >> ~/.bashrc
source ~/.bashrc
# 配置 calico cni 网络
mkdir -p /opt/cni/bin && wget https://github.com/containernetworking/plugins/releases/download/v1.3.0/cni-plugins-linux-amd64-v1.3.0.tgz
tar -xvf cni-plugins-linux-amd64-v1.3.0.tgz -C /opt/cni/bin
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.25.1/manifests/calico.yaml

Environmental inspection, the final deployment situation is as follows:

root@registry:/home/vagrant# kubectl get po -A
NAMESPACE     NAME                                       READY   STATUS    RESTARTS   AGE
kube-system   calico-kube-controllers-5857bf8d58-2p25d   1/1     Running   0          7m46s
kube-system   calico-node-fk6vd                          1/1     Running   0          7m46s
kube-system   coredns-567c556887-8r8cx                   1/1     Running   0          11m
kube-system   etcd-registry                              1/1     Running   2          11m
kube-system   kube-apiserver-registry                    1/1     Running   2          12m
kube-system   kube-controller-manager-registry           1/1     Running   2          11m
kube-system   kube-proxy-vt2ks                           1/1     Running   0          11m
kube-system   kube-scheduler-registry                    1/1     Running   2          11m
kube-system   storage-provisioner                        1/1     Running   0          11m

Since Bioos needs to use NAS storage, we choose to use the NFS storage solution here. For convenient access, we also need to install an Ingress controller to provide network access support.

Install the ingress controller

Ingress deployment can refer to the official website, and you can also refer to the nginx-ingress deployment configuration of kubespray.

# 安装 ingress 控制器(国内可能镜像下载会有问题)
#kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.7.1/deploy/static/provider/cloud/deploy.yaml
# 如果镜像下载有问题，可以使用下面的代码替代
# kubectl apply -f https://raw.githubusercontent.com/markthink/helm-charts/main/StorageClass/base/yaml/ingress-nginx.yaml
git clone https://github.com/markthink/helm-charts
cd helm-charts && kubectl apply -f ingress_nginx/

Environmental inspection, the final deployment situation is as follows:

root@registry:/home/vagrant# kubectl get po -A
NAMESPACE       NAME                                       READY   STATUS    RESTARTS   AGE
ingress-nginx   ingress-nginx-controller-f6c55fdc8-x5dtz   0/1     Running   0          40s
kube-system     calico-kube-controllers-5857bf8d58-2p25d   1/1     Running   0          15m
kube-system     calico-node-fk6vd                          1/1     Running   0          15m
kube-system     coredns-567c556887-8r8cx                   1/1     Running   0          19m
kube-system     etcd-registry                              1/1     Running   2          19m
kube-system     kube-apiserver-registry                    1/1     Running   2          19m
kube-system     kube-controller-manager-registry           1/1     Running   2          19m
kube-system     kube-proxy-vt2ks                           1/1     Running   0          19m
kube-system     kube-scheduler-registry                    1/1     Running   2          19m
kube-system     storage-provisioner                        1/1     Running   0          19m
root@registry:/home/vagrant# kubectl get ingressclass -A
NAME    CONTROLLER             PARAMETERS   AGE
nginx   k8s.io/ingress-nginx   <none>       47s

Install NFS Storage Service

Use helm to install the nfs storage service (please refer to the remarks for Nfs-server deployment) Since you can't download foreign (registry.k8s.io) images in China, you need to prepare the helm configuration file values.yaml:

image:
  nfs:
    repository: dyrnq/nfsplugin
    tag: v4.2.0
    pullPolicy: IfNotPresent
  csiProvisioner:
    repository: dyrnq/csi-provisioner
    tag: v3.3.0
    pullPolicy: IfNotPresent
  livenessProbe:
    repository: dyrnq/livenessprobe
    tag: v2.8.0
    pullPolicy: IfNotPresent
  nodeDriverRegistrar:
    repository: dyrnq/csi-node-driver-registrar
    tag: v2.6.2
    pullPolicy: IfNotPresent

```shell

安装