The KBase SDK is a set of tools for developing KBase Apps that can be dynamically registered and run on the KBase platform. Apps are grouped into modules that include all code, dependencies, specification files, and documentation needed to define and run Apps in the KBase Narrative interface. By using Docker combined with the KBase App Catalog, you can build and run a new "Hello World!" App in KBase in minutes.

There are still some general restrictions on functionality that will gradually be lifted as the SDK and KBase platform are refined. The current restrictions are:

• Runs completely on a standard KBase worker node (at least 2 cores and 22GB memory)
• Operates only on supported KBase data types
• Uses existing data visualization widgets
• Does not require new uploaders/downloaders
• Wrapper written in Python, Java, R, or Perl

If you have a tool you would like to register with KBase that cannot meet these requirements, please contact us to discuss possible solutions.

You can use the SDK to develop and test Apps with a regular KBase user account (and a Git repository). When you’d like us to deploy your App publicly in KBase, please contact us to be added to the developer list.

1. Install SDK Dependencies
2. Install and Build SDK
3. Create Module
4. Edit Module and Method(s)
5. Locally Test Module and Method(s)
6. Register Module
7. Test in KBase
8. Complete Module Info
9. Deploy

• Examples
• FAQ
• Troubleshooting
• KBase Developer Policies
• Anatomy of a KBase Module
• KBase Data Types Table
• Working with KBase Data Types
• KBase Catalog API

Below is a quick reference guide for standard installation. For more complete details and troubleshooting, see the Full Installation Guide.

For the adventurous, there is an experimental Dockerized installation that only requires Docker. It is known to work on at least Mac and Linux, but has not been extensively tested yet. For details, see Dockerized Installation

System Dependencies:

• Mac OS X 10.8+ or Linux. kb-sdk does not run natively in Windows, but see here for more details.
• Java JRE 7+ http://www.oracle.com/technetwork/java/javase/downloads/index.html
• (Mac only) Xcode https://developer.apple.com/xcode
• git https://git-scm.com
• Docker https://www.docker.com (for local testing)

Get the SDK:

git clone https://github.com/kbase/kb_sdk

Pull dependencies and configure the SDK:

cd kb_sdk
make bin

Download the local KBase SDK base Docker image:

make sdkbase 

Add the kb-sdk tool to your PATH and enable command completion. From the kb_sdk directory:

# for bash
export PATH=$(pwd)/bin:$PATH
source src/sh/sdk-completion.sh

Test installation:

kb-sdk help

Additional System Dependencies:

• Java JDK 7+ http://www.oracle.com/technetwork/java/javase/downloads/index.html
• JAVA_HOME environment variable set to JDK installation path
• Apache Ant http://ant.apache.org

Follow basic instructions above. Instead of running make bin you can run make to compile the SDK:

cd kb_sdk
make

Initialize a new module populated with the ContigFilter example (module names need to be unique in KBase, so you should pick a different name):

kb-sdk init --example -l python -u [your_kbase_user_name] MyContigFilter

Enter your new module directory and do the initial build:

cd MyContigFilter
make

Edit the local test config file (test_local/test.cfg) with a KBase user account name and password:

test_user = TEST_USER_NAME
test_password = TEST_PASSWORD

Run tests:

cd test_local
kb-sdk test

This will build your Docker container, run the method implementation running in the Docker container that fetches example ContigSet data from the KBase CI database and generates output.

Inspect the Docker container by dropping into a bash console and poke around, from the test_local directory:

./run_bash.sh

When you make changes to the Narrative method specifications, you can validate them for syntax locally. From the base directory of your module:

kb-sdk validate

Add your repo to GitHub (or any other public git repository), from the MyContigFilter base directory:

cd MyContigFilter
git init
git add .
git commit -m 'initial commit'
# go to github and create a new repo that is not initialized
git remote add origin https://github.com/[GITHUB_USER_NAME]/[GITHUB_REPO_NAME].git
git push -u origin master

Now go to https://appdev.kbase.us/#appcatalog/register. Enter your public git repo url (e.g. https://github.com/[GITHUB_USER_NAME]/[GITHUB_REPO_NAME]) and submit. Wait for the registration to complete. Note that you must be an approved developer to register a new module.

Your app is now available in the AppDev environment in KBase. Go to https://appdev.kbase.us, sign in and start a new Narrative. Click on the small 'R' in the upper right of the Apps panel until it switches to 'D' to show Apps that are still in development. Find your new App by searching for your module, and run it to filter some contigs.

Your App will now also be visible in the App Catalog when displaying Apps in development: https://appdev.kbase.us/#appcatalog/browse/dev and https://narrative.kbase.us/#appcatalog/browse/dev. From your module page (e.g., https://narrative.kbase.us/#appcatalog/module/[MODULE_NAME]) you'll be able to register any update and manage release of your module to the production KBase environment for anyone to use.

Now, dive into Making your own Module.

There are a number of modules that we continually update and modify to demonstrate best practices in code and documentation and present working examples of how to interact with the KBase API and data models.

• MegaHit (Python) - assembles short metagenomic read data (Read Data -> Contigs)
• Trimmomatic (Python) - filters/trims short read data (Read Data -> Read Data)
• OrthoMCL (Python) - identifies orthologous groups of protein sequences from a set of genomes (Annotated Genomes / GenomeSet -> Pangenome)
• ContigFilter (Python) - filters contigs based on length (ContigSet -> ContigSet)

Browse through the doc directory of this repo for the latest avaialble documentation. If you still have questions or comments, please create a GitHub issue or pull request, or contact us through http://kbase.us/contact-us