Quick Start

This is the fastest path to a running bioAF. If you’d rather click through the GCP Console yourself, see Manual Installation > Setup & Deploy instead.

What you’ll have when you’re done

  • A web-based control plane for your entire comp bio workflow
  • Pipeline execution (Nextflow, nf-core, and custom pipelines) with a built-in catalog
  • Notebook sessions (JupyterHub, RStudio) with versioned environments
  • Structured experiment and sample tracking
  • Interactive results visualization (cellxgene, QC dashboards)
  • Cost monitoring and audit logging

Quick start

Before running the installer, make sure you’ve completed the Prerequisites (Google account, Google Cloud project, billing).

Pick your operating system:

Run this in your terminal:

bash <(curl -fsSL https://raw.githubusercontent.com/bioAF/bioAF/main/install-gcp.sh)

Provisions a GCP VM, firewall rule, and service account. Prefer to do it by hand? Follow the manual install steps.

When the script finishes, it prints the SSH command to connect to your new VM. The installer attaches a scoped service account (bioaf-app) directly to the VM, so no JSON key is downloaded or stored on your laptop.

Install bioAF on the VM

Once you’re SSH’d in, clone the repo and run setup.

Clone the bioAF repo

git clone https://github.com/bioAF/bioAF.git

Run ./bioaf setup

cd bioAF && ./bioaf setup

./bioaf setup checks prerequisites, generates configuration, builds the container images, runs migrations, and starts the services. It takes about 30 minutes on a fresh VM.

When it finishes, the console prints:

  • The URL of the setup wizard (typically https://<your-vm-ip>/setup)
  • A one-time setup code that expires in one hour

Keep both visible, you’ll use them in the web UI next.

Set up bioAF in the web UI

Open the setup wizard URL in your browser and walk through the first-run flow.

1. Paste the one-time setup code

The code was printed on the VM’s console by ./bioaf setup. Pasting it proves you have admin access to the instance.

i Lost the code or it expired?
Re-run ./bioaf setup on the VM. It mints a fresh code as long as no admin account has been created yet. Once the first admin exists, the wizard closes.

2. Create your admin user

Pick an email and password. This becomes the first account with full admin rights.

3. Confirm your GCP identity

The wizard auto-detects the service account attached to the VM (bioaf-app) and pre-populates your project, region, and the bioaf-bootstrap SA email from the VM’s metadata. Confirm the values look right and continue. No JSON key is needed for either the scripted or manual path; the runtime impersonates bioaf-bootstrap for broader operations using short-lived tokens.

4. Configure SMTP (optional)

Add SMTP server details if you want bioAF to send invitation and notification emails. You can skip this and configure it later under Admin > SMTP Settings.

bioAF’s components (GKE, Cloud SQL, GCS buckets, JupyterHub, cellxgene, etc.) are enabled individually so you only pay for what you use. Review the cost estimates and toggle on the ones your team needs.

For a typical scRNA-seq team, a good starting set is:

  • GKE cluster: required for pipelines and notebooks
  • Cloud SQL: required for the database
  • GCS buckets: required for data storage
  • JupyterHub or RStudio, for interactive analysis
  • cellxgene: for single-cell visualization

Skip this step if you just want to explore the UI first. You can enable components any time from Admin > Component Settings.

Next steps