Creating a 'Run on FloydHub' Button¶
The 'Run on FloydHub' button enables users to run CPU or GPU-powered workspaces on FloydHub with little or no configuration. The button is ideal for sharing open-source projects, reproducing academic research papers, teaching educational courses to students, and anywhere else you want people to be able to quickly run and reproduce your projects.
The button is well-suited for use in README files, and is intended to serve as a replacement for the manual configuration of your environment, code, and data required to reproduce your work.
Here's an example button that trains a sentiment analysis TensorFlow model on FloydHub (including attaching the required datasets):
This document describes the requirements for using the 'Run on FloydHub' button, and how to use these buttons to make it easy to run, reproduce, and share your projects on FloydHub.
floyd.yml is a configuration file describing your FloydHub deep learning environment. It declares your machine type, deep learning framework (e.g. TensorFlow, PyTorch), attached datasets, and other information for running jobs and workspaces on FloydHub.
There are no specific tools required to create a
floyd.yml for your project. The
floyd.yml schema has only two required fields:
Here's a sample
env: tensorflow-1.8 machine: gpu
If your app requires any datasets, those can be specified in the
env: tensorflow-1.7 machine: cpu data: - source: floydhub/datasets/imdb-preprocessed/1 destination: imdb
For more information, view the floyd.yml schema documentation.
Testing the floyd.yml file¶
Now that you've created a
floyd.yml file for your project and added it to the project's repo on GitHub, you can easily test that it is valid and that your project can be successfully created. Use your web browser to visit:
If this was successful, then you should be able to automatically create a new project along with a Workspace that contains your repo's code.
Adding the FloydHub button¶
Once you've verified that your
floyd.yml file is valid and working as expected, it's time to add a button to your repo README.
There are two ways of referencing the template source code repository:
Basic Setup This is the preferred approach. Add the button code without specifying the URL of your repository. This is best for GitHub-hosted documentation on your project's README. If you don't specify a
templateparameter, FloydHub infers it from the location of the button using the
referrerheader. This makes the button stable under forks of the repository.
Advanced Setup: Using an explicit
templatequery parameter that points to the repo. This is useful for buttons sitting outside of GitHub, such as in blog posts or documentation (like this page!)
If you're embedding the button in a GitHub repository's README file, FloydHub will automatically infer the repository URL from the
referrer header when someone clicks the button.
Using an implicit template
This is convenient because it avoids hard-coding the specific repository URL into the button, allowing forks of the repository to work properly without a change to the button href.
Here's an example that you can copy and paste directly into your own project's README file:
[![Run on FloydHub](https://static.floydhub.com/button/button.svg)](https://floydhub.com/run)
Here's the equivalent content as HTML:
<a href="https://floydhub.com/run"> <img src="https://static.floydhub.com/button/button.svg" alt="Run"> </a>
Use the following Markdown snippet as a template, changing the
template query paramter to the URL of your repository:
[![Run on FloydHub](https://static.floydhub.com/button/button.svg)](https://floydhub.com/run?template=https://github.com/floydhub/sentiment-analysis-template)
Here's the equivalent content as HTML:
<a href="https://floydhub.com/run?template=https://github.com/floydhub/sentiment-analysis-template"> <img src="https://static.floydhub.com/button/button.svg" alt="Run"> </a>
You can access the link to the 'Run on FloydHub' button image (as a SVG file) here:
Does this work with private repos?¶
No, not right now. We are planning to add support for running for private repos.
Does this work with branches?¶
No, not right now. We are planning to add support for running from branches.
Does this only work with repos on GitHub?¶
Where can I ask more questions or provide feedback on the Run on FloydHub button?¶
We'd love to hear your questions and feedback on the Run on FloydHub button, so please send us an email.