Build the Docker Image
Once the run script, and Dockerfile have been created, it is time to build the Docker image for the Gear. There are two steps that need to be taken to create the image:
Place all components (manifest file, run script, and Dockerfile) into a directory
Create the Docker image:
$ docker build --tag $GEAR_NAME $DIR
GEAR_NAME is the name of the Docker image to be created, use the name of the gear
DIR is the pathname to the directory containing all of the gear components
If no errors occurred, the image should have successfully built. Enter the command
$ docker images to get the list of the Docker images. The output should look similar to the following output:
If successful, the name of the Gear (
$GEAR_NAME) should be at the top of the “REPOSITORY” column.
Create the Gear
Once the required software is installed and the Docker image is available, you can execute the following commands within a Terminal window to create the Gear. The main purpose of this step is to generate a valid manifest for gear upload and execution.
*Note: THIS STEP IS NOT RECOMMENDED IF you have already generated a custom manifest with the "custom.gear-builder" key (which is required for upload). Following these commands when you already have a custom manifest will modify fields within that manifest and may lead to unintended results on upload.
- Create and cd into a new working directory
Login to the Flywheel CLI
$ fw login $APIKEY
Where $APIKEY is user’s API Key which can be found through the Flywheel UI on the User’s profile page
Create the gear
$ fw gear create
Follow the prompts
- Update the manifest.json file to include any custom edits that are desired*.
* Note: The manifest.json and run script of the Gear will be placed in the working directory. Manifest files found within a given image will be placed within the working directory, however that manifest will be augmented by the Flywheel CLI so be sure to make any updates to the manifest.json within the working directory prior to upload!
Testing the Gear
Once the Gear is built, it is important to test it locally prior to uploading to Flywheel. This local testing can be done using the CLI.
To understand the flags that must be passed to the Gear during a local run, log in and use the following command*:
$ fw gear local --help
Once you have your arguments set, you can execute the local test using:
$ fw gear local --<flag>=<value>
Once the Gear finishes running, outputs will be placed in the working directory within a directory named `outdir`.
* Note that older versions of the CLI used the command `fw gear run`. If you are using one of these older versions, we would encourage you to upgrade to the latest CLI version.
Upload the Gear
Now that the Gear is created and runs locally, the next step is to upload the gear to the Flywheel platform. This is done using the CLI as well, like so:
$ fw login <api_key>
$ fw gear upload
Note that this command uses information provided in the manifest to determine the Gear category on upload (i.e. analysis vs. utility).
Confirm Gear Upload
To confirm the gear upload was successful, visit the institution’s Flywheel site and click on “Gears” on the left column menu. All gears available will be listed. Search for the recently uploaded gear using the search bar in the upper left hand corner of the page.