Gear Building Tutorial Part 1: Developers, Start Your Environments!

Introduction

Welcome to the Flywheel development tutorial!  In this section, you'll learn what tools and software you'll need to begin developing gears, and how to install them.  This section will provide you the bare minimum needed to get each piece of software working, but there will be links to more extensive information and documentation.  As your gears become more advanced, it's likely that you'll need these more detailed references.

Before we can proceed, make sure you have a Flywheel account with an associated API key.

Getting 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 the environment, you will need to be added as a user to your site by your local Site Admin.  Your site Administrator must add you as a developer or site admin in Flywheel. Note that being project admin does not give you the ability to upload gears, only site admin status allows that. Once you have admin privileges, you'll be able to begin creating gears.  

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 status to upload your gear at the end of this tutorial. 

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. Flywheel Command-Line Interface
  3. Flywheel SDK

Docker

Docker is a program that allows you to create "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".  You 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.  That will be covered later in this tutorial.  

For now, we only need to install Docker.

Install Docker

Docker comes in two flavors: Community Edition (CE)  and Enterprise Edition (EE). EE is a paid version of Docker, and it has more support provided from Docker themselves.   CE is a free docker engine, but don’t worry, they can do exactly the same things. Unless your lab is going to get a professional EE docker account, download the CE edition. 

  1. Verify your computer meets Docker's system requirements. See Docker's documentation: 
  1. Follow Docker's instructions for creating an account and installing the app:
    1. Create a Docker account, and sign in
    2. Install Docker: 

How do I know I did this step correctly?

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 you need to know about Docker in the context of Flywheel gears.   

Logging in to docker

Before you can fully utilize docker, and docker hub (essentially a repository for any docker images you make, so they can be accessed anywhere from any computer), you must first create a docker hub account.  To do this, visit dockerhub, and clicking "Sign up for dockerhub".  This will prompt you to generate a username and password.  Your username will be associated with all your docker images, so pick something easy to spell and remember.  

Once you've generated your account, open a terminal on your machine and link your account to docker by typing the following:

docker login

 You will then be prompted for your docker username and your docker 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.  

 

Flywheel CLI

The Flywheel CLI is a tool that allows us to interact with Flywheel and our data from our Terminal (or command line).  With the CLI, you can view, download, and upload data, run jobs, build and test gears, and more. For more examples of what you can do with the Flywheel CLI. see our article on that topic. However, we'll be focusing on the gear-specific aspects of the CLI, which will be covered later in this tutorial.

Install the Flywheel CLI

Follow these steps to install the Flywheel CLI

How do I know I did this step correctly?

If you successfully logged in with your API key 

fw login <yourapikey>

then you should see the message:

You are now logged in as <username>!

If this works, your installation is successful.  

Common Problems

If you see a message like the following:

“Invalid API key format. Please re-generate in the Flywheel user interface.”

Then the installation was successful, however there's something wrong with the API key used to login.  Review step 3 and 4 from the CLI installation page to ensure that you correctly generated and copied your API key.  If the problem persists, contact your site administrator.

If you receive an error like the following:

-bash: fw: command not found

It's possible that your PATH variable is not set up correctly, or the CLI did not install successfully.    

Flywheel SDK

The Flywheel SDK is a multi-language package with a vast array of tools that give user a programmatic access to the Flywheel API endpoints (Essentially, commands you can call to retrieve and manipulate data on Flywheel).  Although it's not strictly required for running gears, it is an extremely powerful tool for any gear-builder, and it's highly recommended that you utilize it as much as possible. 

Requirements

To use the Flywheel , you will need to have both Python and pip installed on your machine.  pip is just a tool to automatically download and install additional libraries to python on your local machine.

See these resources to learn how to install python, and install pip.

Install the Flywheel SDK

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

pip install flywheel-sdk

How do I know I did this step correctly?

To verify that you installed the 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 Problems

If this installation failed, some common problems are as follows:

  • 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.  The version of pip and python can be checked with "pip --version" and "python --version".  It's possible you may need to manually specify the version of pip to install flywheel-sdk (e.g. "pip3.7 install flywheel-sdk").  

See our Python SDK docs for more information.

That's it!  You're ready to start building your very first gear!  In the next section, we'll teach you the very basics of how to use these tools specifically for flywheel gear development.  

Resources from this section

Flywheel Account Info

Docker

Flywheel CLI

Flywheel SDK

Navigation

Part 1: Environment Setup

Part 2: Gear Intro

Part 2a: The Flywheel Environment

Part 2b: The Run Script

Part 2c: The Manifest

Part 2d: The Dockerfile 

Part 2e: Testing/Debugging

Related articles