Gear Building Tutorial Part 1: Developers, Start Your Environments! – Flywheel.io

Introduction

Welcome to the Flywheel development tutorial! In this document, you'll learn what tools and software that will be needed 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. As your gears become more advanced, it's likely that you'll need these more detailed references.

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

Obtaining 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:

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

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.

Verify your computer meets Docker's system requirements. See Docker's documentation:
- Mac
- Linux
- Windows

Follow Docker's instructions for creating an account and installing the app:
1. Create a Docker account, and sign in
2. Install Docker:
  - Linux
  - Mac
  - Windows

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

Logging in to Docker

Before one 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), first create a docker hub account. To do this, visit dockerhub, and click Sign up for dockerhub. This will prompt one to generate a username and password. The 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

The User will then be prompted for their docker username and 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 as shown below, then that means the installation was successful.

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

The installation may have been successful; however, there's something wrong with the API key used to login. Review step 3 and 4 from theCLI 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 as shown below, then it is possible that your PATH variable is not set up correctly, or the CLI did not install successfully.

-bash: fw: command not found

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 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, one will need to have both Python and pip installed on their 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:

Open a Python interpreter.
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.