Skip to content

Gear Building Tutorial Part 1: Developing Gears

Introduction

Welcome to the Flywheel Gear Building Tutorial!  In this Part, we'll learn what tools and software we need to begin developing gears and how to install them. This section will provide the bare minimum needed to get each piece of software working, but there will be links to more extensive information and documentation.

Instruction Steps

The Flywheel Development Environment

The Flywheel development environment in this case refers to the software we use to create, test, and run our gears.  The environment consists of three major parts, each of which will be covered in the following sections:

  1. Docker
  2. New Flywheel CLI (currently in BETA)
  3. Flywheel SDK

Docker

Docker is a program that allows you to create containers, or as they put it, "standard units of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another."  In other words, you set up a self-contained environment with any OS, any specific software you want at any specific version, and any other custom settings you may wish to include, and Docker packages all these settings into something called an image. One can then run this image identically on any machine that also has Docker. When an image is run, it creates a self-contained environment called a container. The image is basically a piece of software stored on your computer, while the container is the object that’s created when you run that software.  No more worrying about versions, dependencies and operating systems!  In a way, you can think of this as a super lightweight virtual machine that can run on any computer that also has Docker.  

To ensure that our gears will run anywhere, we use Docker to create images, which we then run our gears on.  Each gear may have a custom Docker image, depending on the system or software requirements of that gear. As a developer, you will choose and specify exactly what kind of docker image you want to run your gear on. Docker images will be covered later in this tutorial.  

New Flywheel CLI (currently in BETA)

The New Flywheel CLI (currently in BETA) is a tool that allows us to interact with Flywheel and our data from our Terminal (or command line).  With the New Flywheel CLI, we can view, download, and upload data, run jobs, build and test gears, and more. For more examples of what we can do with the New Flywheel CLI, check out the documentation. However, we'll be focusing on the gear-specific aspects of the New CLI (fw-beta gear), which will be covered in Part 7 of this tutorial.

New Flywheel CLI not available on Windows

Right now, the New Flywheel CLI is only available for download on Mac and Linux.

Flywheel SDK

The Flywheel SDK is a multi-language package with a vast array of tools that provides users with programmatic access to the Flywheel API endpoints which are commands one can call to retrieve and manipulate data in Flywheel. Although it's not strictly required for running gears, it is an extremely powerful tool for any gear builder. The Flywheel SDK package is available for both Python and Matlab. For this tutorial, we will be focusing on the gear-specific functionality of the Python version of this package.

Next steps

Now that we've learned about the three major parts of the Flywheel development environment, let's start by first making sure we have an active Flywheel account with the correct permissions level.

Step 1. Obtain a Flywheel Account

Each institution that uses Flywheel has their own dedicated instance of the Flywheel platform and a unique URL (e.g. https://yourinstitution.flywheel.io).

Before getting started with this tutorial, you will need to be added as a developer to your site by a Site Admin of your local site.  They must add you as a developer or site admin in Flywheel.

Project admin vs Site admin

Being project admin or similar does not give you the ability to upload gears, only site roles of Developer or Site Admin allow this. In order to upload your custom gears in your Flywheel UI, you will need Site Admin or Developer privileges.

After you ensure that you are a user on your Flywheel instance, we can set up the rest of our tools.  Remember, you’ll need Site Admin or Developer status to upload your gear at the end of this tutorial.

Step 2. Install Docker

The easiest way to get Docker installed on your local system is to install the Docker Desktop app. Docker is open and free to use, however, there are paid subscription requirements for commercial use.

  1. Verify your computer meets Docker's system requirements. See Docker's documentation:

  2. Follow Docker's instructions for creating an account and installing the app:

    1. Create a Docker account, and sign in
    2. Install Docker:

Checking the Docker Installation

Open a new terminal window and type docker.  A long list of usage options should appear on your screen, starting with:

Usage: docker [OPTIONS] COMMAND  
A self-sufficient runtime for containers

This indicates successful installation!  

See Docker’s documentation for more information.  It's not necessary to have an in-depth understanding of every aspect of Docker.  In later sections of the tutorial, we'll cover what is needed to know about Docker in the context of Flywheel gears.

Logging in to Docker

Once you've successfully installed Docker, type the following in a terminal window to link your local Docker installation to your Docker Hub account:

docker login

You will then be prompted for your Docker username and password.  

Once login is successful, you'll be able to push repos to your Docker Hub account, which will be discussed later in this tutorial.  

Step 3. Install the New Flywheel CLI (currently in BETA)

Follow these steps to install the New Flywheel CLI. You can also find installation instructions for the New CLI from your profile page on your Flywheel instance.

New CLI vs Classic CLI

For the purposes of this tutorial, make sure that you are installing and working with the "New CLI" rather than the "Classic CLI". Under your profile page on your Flywheel instance, it is referred to as, "Flywheel CLI • New (in Beta)". It is currently only available for macOS and Linux customers. Both the "New CLI" and the "Classic CLI" use the same API keys.

Checking your New Flywheel CLI installation

To check the installation of the New Flywheel CLI, from a terminal window type:

fw-beta

If the installation was successful, you should see the usage statement (abbreviated below):

Flywheel CLI (beta) <version number>

USAGE
  fw-beta [OPTIONS] COMMAND [ARGS]...

COMMANDS
...

Logging in with your API key

When we get to testing our gear and ultimately uploading our gear to our Flywheel instance, we will need to be logged into our Flywheel instance using an API key. Follow these instructions for generating a User API key.

Once you have generated and saved your API key, type the following to log in using the New CLI:

fw-beta login

which will prompt you to input your API key.

If you have your API key stored as an environmental variable in your profile, you can use:

fw-beta login --api-key <apikey>

Once you successfully log in with your API key, you should see the following message:

Logged in to <your.instance.flywheel.io> as <username> (profile: default)

If this works, your installation is successful.  

Common Installation Problems

  1. Error with API Key

    If you see a message as shown below, then that means the installation was successful. However, there is something wrong with the API key used to log in. Review steps in the Creating a User API Key page to ensure that you correctly generated and copied your API key.  If the problem persists, contact your site administrator. 

    Error: Invalid API key format - expected <site>:<key>

  2. Path error or unsuccessful installation

    If you receive an error as shown below, then it is possible that your PATH variable is not set up correctly, or the New CLI did not install successfully.

    -bash: fw-beta: command not found

Step 4. Install Flywheel SDK

Requirements

To use the Flywheel SDK, you will need to have both Python and pip installed on your machine.  pip is a tool to automatically download and install additional libraries to Python on your local machine. If you install Python from an official source, pip should automatically be installed during the Python installation.

See these resources to learn how to install python and install pip.. You can also install Python via an Integrated Development Environment.

Installing the Flywheel SDK package

Once you have installed Python and pip, enter the following into your terminal window:

pip install flywheel-sdk

Checking the Installation

To verify that you installed the Flywheel SDK package:

  1. Open a Python interpreter.
  2. Run the following command to verify installation:
import flywheel

If this command runs without any error messages, it is installed correctly.

Common Installation Problems

It's possible your machine has multiple versions of Python installed.  flywheel-sdk needs to be installed to the Python version you're using in your coding (at this point python>3.8).  The version of pip and Python can be checked with pip --version and python --version.  You may need to manually specify the version of pip to install flywheel-sdk (e.g. pip3.8 install flywheel-sdk).

It is also possible that you have multiple copies of the flywheel-sdk package installed in multiple locations. In this case, you will need to set up a PATH variable to point to the desired version of the package.

See our Python SDK docs for more information.

Wrapping Up

In this part, we have briefly introduced the three main tools we need for gear development and testing in Flywheel: Docker, the New Flywheel CLI (currently in BETA), and the Flywheel SDK. We have walked through installing and testing the installations for these three tools. We're ready to start building your very first gear!  In Part 2 Creating Your First Gear, we will cover the main files each gear needs and how Flywheel uses these files when running a gear.

Additional Resources

Flywheel Account Information

Docker

New Flywheel CLI (currently in BETA) and User API keys

Flywheel SDK

Next Part 2 Creating Your First Gear