Skip to main content

Getting Started with BoCoFlow

This guide will help you install BoCoFlow, set up your first workflow, and understand the basics of the interface.

1. Download the Desktop Application​

BoCoFlow is available as a desktop application for macOS and Linux, with Windows support coming soon.

System Requirements​

  • Operating System: macOS 13.6+, Ubuntu 24.03+, or other Linux distributions via AppImage
  • RAM: 4GB minimum, 8GB recommended
  • Disk Space: 500MB for the application, plus space for your workflows and data
  • Python: Python 3.9+

Download and Install​

  1. Download the latest BoCoFlow installer from the official website:

    • macOS (13.6+)
    • Linux (AppImage - Portable)
    • Ubuntu 24.03+ (.deb)
    • Windows (Coming soon)

  2. Run the installer and follow the on-screen instructions.

    tip

    The macOS app and Linux AppImage are portable and don't require installation.

  3. Launch BoCoFlow after installation completes.

2. Set Up Your Computational Environment​

BoCoFlow can run immediately after installation, but to execute computational tasks, you'll need to set up a conda environment. This approach ensures maximum flexibility and extensibility for your workflows.

note

For new users: Don't worry about the computational environment setup. This approach guarantees maximum extensibility while remaining straightforward to configure.

Set Up Conda (Miniconda) Environment​

  1. Download the Miniconda installer from the official website
  2. Run the installer and follow the on-screen instructions
  3. Activate the base conda environment

Install Our Demonstration Workflow's Dependencies

Our demonstration workflow is based on the pdbmdauto project. We've created an environment YAML file to simplify setup.

  1. Download the pdbmdauto_environment.yml file from GitHub

  2. Create the conda environment:

# Create a new environment from the YAML file
conda env create -f pdbmdauto_environment.yml

# If you need to update an existing environment
conda env update -f pdbmdauto_environment.yml
  1. Activate the conda environment:
conda activate pdbmdauto
  1. Note the conda installation path (e.g., /Users/yourname/miniconda3) for configuring BoCoFlow later.

Optional: Install Docker​

Some nodes in our demonstration workflow utilize Docker. To use these nodes:

  1. Download and install Docker Desktop
  2. Start Docker Desktop and keep it running in the background

Helpful Resources​

tip

If you're new to conda or Docker, don't worry! Contact us if you have any questions.

3. Practice with a Production Workflow​

Instead of starting with a simple toy workflow, we've included nodes from a production workflow called pdbmdauto, which provides a comprehensive pipeline for homology modeling and molecular dynamics simulation.

Video Tutorial​

Watch our comprehensive tutorial that walks through setting up and running a complete workflow:

Step-by-Step Guide​

a. Project Setup​

  1. Launch BoCoFlow and click the Setup button in the top toolbar.

  2. In the New Workflow tab:

    • Set your Working Directory where workflow files and data will be stored
    • Optionally configure a Custom Nodes Directory if you have specialized nodes
    • Select a Database Type (SQLite recommended for beginners)
    • Choose Log Level (Error for production, Verbose for troubleshooting)
    • Set up your Conda Environment by providing the path to your conda installation (e.g., /Users/yourname/miniconda3)
    • If using the pdbmdauto example, specify pdbmdauto as the Default Conda Environment

  3. Click Create Workflow to complete the setup.

b. Common Operations​

Working with Nodes

  • Drag nodes from the Node Menu (left sidebar) onto the canvas
  • Connect nodes by dragging from an output port (right side) to an input port (left side) of another node
  • Configure nodes by clicking the ⚙️ (gear) icon and filling in required fields
  • Search for specific nodes using the search bar at the top
  • View node results by clicking the 📊 (chart) icon

Workflow Management

  • Execute your workflow by clicking the Execute button
  • Save your workflow using the Save button
  • View execution logs in the panel at the bottom of the screen
  • Access detailed backend logs through the menu: View → Toggle Backend Logs

Understanding the Interface​

BoCoFlow's interface is designed to be intuitive and efficient:

Toolbar​

The top toolbar provides essential controls:

  • Setup: Configure workspace settings
  • Save: Save your current workflow
  • Clear: Clear the current workflow
  • Execute: Run the entire workflow
  • Search: Find nodes by ID

Node Menu​

The left sidebar displays all available nodes organized by categories based on their function and location in the nodes directory. You can search for nodes by name using the search field at the top of the menu.

Canvas​

The central canvas is where you build your workflow:

  • Drag and drop nodes from the Node Menu
  • Connect nodes by dragging between ports
  • Rearrange nodes by dragging them to different positions
  • Zoom and pan to navigate using the controls in the top-right corner

Log Panel​

The bottom panel displays execution logs, including:

  • Success and error messages for each node
  • Execution status throughout the workflow
  • Timestamps for tracking execution progress

Node States and Execution​

Nodes in BoCoFlow have distinct visual states that indicate their status:

  • Unconfigured (Red): Nodes that need setup before execution
  • Configured (Yellow): Nodes that are set up but not yet executed
  • Complete (Green): Nodes that have successfully executed
  • Failed (Red): Nodes that encountered errors during execution

Next Steps​

Now that you've created your first workflow, explore more about BoCoFlow:

Need help? Join our community forum or contact support.